Specification 1.6

October 18, 1999

Open Financial Exchange Specification Legend

A royalty-free, worldwide, and perpetual license is hereby granted to any party to use the Open

Financial Exchange Specification to make, use, and sell products and services that conform to

this Specification.

THIS OPEN FINANCIAL EXCHANGE SPECIFICATION IS MADE AVAILABLE “AS IS”

WITHOUT WARRANTY OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED BY

APPLICABLE LAW, MICROSOFT, INTUIT AND CHECKFREE (“PUBLISHERS”) FURTHER

DISCLAIM ALL WARRANTIES, INCLUDING WITHOUT LIMITATION ANY IMPLIED

WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

NONINFRINGEMENT, ALL OF WHICH ARE HEREBY DISCLAIMED. THE ENTIRE RISK

ARISING OUT OF THE USE OF THIS SPECIFICATION REMAINS WITH RECIPIENT. TO THE

MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL THE

PUBLISHERS OF THIS SPECIFICATION BE LIABLE FOR ANY CONSEQUENTIAL,

INCIDENTAL, DIRECT, INDIRECT, SPECIAL, PUNITIVE, OR OTHER DAMAGES

WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS

PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER

PECUNIARY LOSS) ARISING OUT OF ANY USE TO WHICH THIS SPECIFICATION IS PUT,

EVEN IF THE PUBLISHERS HEREOF HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH

DAMAGES.

OFX 1.6 Specification iii10/18/99

TABLE OF CONTENTS

Chapter 1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.1.1 Design Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

1.2 Open Financial Exchange at a Glance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

1.2.1 Data Transport. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

1.2.2 Request and Response Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

1.3 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.3.1 User. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.3.2 Financial Institution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.3.3 Service Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.3.4 Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

1.3.5 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

1.3.6 Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

1.3.7 Tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

1.3.8 Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

1.3.9 Aggregate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

1.3.10 Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.3.11 Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.3.12 Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.3.13 Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.3.14 Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.3.15 Message Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

1.4 OFX Versions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

1.5 Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 2 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

2.1 HTTP Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

2.2 Open Financial Exchange Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

2.2.1 OFXHEADER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

2.2.2 DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

2.2.3 VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

2.2.4 SECURITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

2.2.5 ENCODING and CHARSET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

2.2.6 COMPRESSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

2.2.7 OLDFILEUID and NEWFILEUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

iv OFX 1.6 Specification10/18/99

2.3 SGML Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

2.3.1 Compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

2.3.2 Valid SGML Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

2.3.3 Comments Not Supported. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

2.4 Open Financial Exchange SGML Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

2.4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

2.4.2 Case Sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

2.4.3 Top Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

2.4.4 Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

2.4.5 Message Sets and Version Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

2.4.6 Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

2.4.7 Synchronization Wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

2.4.8 Message Set Wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

2.5 The Signon Message Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

2.5.1 Signon <SONRQ> <SONRS> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

2.5.2 USERPASS Change <PINCHRQ> <PINCHRS> . . . . . . . . . . . . . . . . . . . . . . . . . 54

2.5.3 <CHALLENGERQ> <CHALLENGERS> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

2.5.4 Signon Message Set Profile Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

2.5.5 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

2.6 External Data Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

2.7 Extensions to Open Financial Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Chapter 3 Common Aggregates, Elements, and Data Types . . . . . . . . . . . . . 61

3.1 Common Aggregates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

3.1.1 Identification of Financial Institutions and Accounts . . . . . . . . . . . . . . . . . . . . . 61

3.1.2 Format of User-Supplied Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

3.1.3 Echoing in Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

3.1.4 Balance Records <BAL>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

3.1.5 Error Reporting <STATUS> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

3.2 Common Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

3.2.1 Client-Assigned Transaction UID <TRNUID>. . . . . . . . . . . . . . . . . . . . . . . . . . . 65

3.2.2 Server-Assigned ID <SRVRTID>, <SRVRTID2> . . . . . . . . . . . . . . . . . . . . . . . . . 66

3.2.3 Financial Institution Transaction ID <FITID> . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

3.2.4 Token <TOKEN>, <TOKEN2> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

3.2.5 Transaction Amount <TRNAMT> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

3.2.6 Memo <MEMO>, <MEMO2> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

3.2.7 Date Start and Date End <DTSTART> <DTEND> . . . . . . . . . . . . . . . . . . . . . . . 69

3.2.8 Common Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

3.2.9 Amounts, Prices, and Quantities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

OFX 1.6 Specification v10/18/99

3.2.10 Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

3.2.11 Other Basic Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Chapter 4 OFX Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

4.1 Security Concepts in OFX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

4.1.1 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

4.1.2 Security Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

4.1.3 Security Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

4.1.4 FI Responsibilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

4.1.5 Security Levels: Channel vs. Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

4.2 Security Implementation in OFX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

4.2.1 Channel-Level Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

4.2.2 Application-Level Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Chapter 5 International Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

5.1 Language and Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

5.2 Currency <CURDEF> <CURRENCY> <ORIGCURRENCY>. . . . . . . . . . . . . . . . . . . . 87

5.3 Country-Specific Element Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Chapter 6 Data Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

6.2 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

6.3 Data Synchronization Approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

6.4 Data Synchronization Specifics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

6.4.1 Tokens. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

6.4.2 The Synchronization Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

6.4.3 Synchronizable Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

6.4.4 <SYNCERROR> Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

6.5 Conflict Detection and Resolution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

6.6 Synchronization Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

6.6.1 Synchronization Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

6.7 Typical Server Architecture for Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

6.8 Typical Client Processing of Synchronization Results . . . . . . . . . . . . . . . . . . . . . . . . . 103

6.9 Simultaneous Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

vi OFX 1.6 Specification10/18/99

6.10 Synchronization Alternatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

6.10.1 File-Based Error Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

6.10.2 Lite Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

6.10.3 Relating Synchronization and Error Recovery . . . . . . . . . . . . . . . . . . . . . . . . 108

6.11 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Chapter 7 FI Profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

7.1.1 Message Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

7.1.2 Version Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

7.1.3 Batching and Routing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

7.1.4 Client Signon for Profile Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

7.1.5 Profile Request <PROFRQ>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

7.2 Profile Response <PROFRS>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

7.2.1 Message Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

7.2.2 Signon Realms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

7.2.3 Status Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

7.3 Profile Message Set Profile Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Chapter 8 Activation & Account Information . . . . . . . . . . . . . . . . . . . . . . . . . 125

8.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

8.1.1 Sign-Up Message Set V2 and Proxy On-Behalf-Of Actions . . . . . . . . . . . . . . . 125

8.2 Approaches to User Sign-Up with OFX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

8.2.1 Multiple User Enrollment and Activation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

8.2.2 Rapid Signup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

8.3 Users and Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

8.4 Enrollment and Password Acquisition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

8.4.1 User IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

8.4.2 Enrollment Request <ENROLLRQ>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

8.4.3 Enrollment Response <ENROLLRS>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

8.4.4 Enrollment Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

8.4.5 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

8.5 Account Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

8.5.1 Request <ACCTINFORQ>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

8.5.2 Response <ACCTINFORS>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

8.5.3 Account Information Aggregate <ACCTINFO> . . . . . . . . . . . . . . . . . . . . . . . . 136

8.5.4 Status Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

8.5.5 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

OFX 1.6 Specification vii10/18/99

8.6 Service Activation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

8.6.1 Activation Request <ACCTRQ>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

8.6.2 Activation Response <ACCTRS> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

8.6.3 Status Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

8.6.4 Service Activation Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

8.6.5 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

8.7 Name and Address Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

8.7.1 Change User Information Request <CHGUSERINFORQ> . . . . . . . . . . . . . . . . 147

8.7.2 Change User Information Response <CHGUSERINFORS> . . . . . . . . . . . . . . . 148

8.7.3 Status Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

8.7.4 Change User Information Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

8.8 Signup Message Set Profile Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Chapter 9 Customer to FI Communication . . . . . . . . . . . . . . . . . . . . . . . . . . 155

9.1 The E-Mail Message Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

9.2 E-Mail Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

9.2.1 Regular vs. Specialized E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

9.2.2 Basic <MAIL> Aggregate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

9.2.3 E-Mail <MAILRQ> <MAILRS> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

9.2.4 E-Mail Synchronization <MAILSYNCRQ> <MAILSYNCRS> . . . . . . . . . . . . . 160

9.2.5 E-Mail Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

9.3 Get HTML Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

9.3.1 MIME Get Request and Response <GETMIMERQ> <GETMIMERS> . . . . . . . 164

9.3.2 MIME Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

9.4 E-Mail Message Set Profile Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Chapter 10 Recurring Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

10.1 Creating a Recurring Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

10.2 Recurring Instructions <RECURRINST> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

10.2.1 Values for <FREQ>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

10.2.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

10.3 Retrieving Transactions Generated by a Recurring Model . . . . . . . . . . . . . . . . . . . . 173

10.4 Modifying and Canceling Individual Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 173

10.5 Modifying and Canceling Recurring Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

10.5.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

10.6 Expired Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

viii OFX 1.6 Specification10/18/99

Chapter 11 Banking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

11.1 Consumer and Business Banking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

11.2 Credit Card Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

11.3 Common Banking Aggregates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

11.3.1 Banking Account <BANKACCTFROM> and <BANKACCTTO> . . . . . . . . 178

11.3.2 Credit Card Account <CCACCTFROM> and <CCACCTTO> . . . . . . . . . . . 183

11.3.3 Bank Account Information <BANKACCTINFO> . . . . . . . . . . . . . . . . . . . . . . 184

11.3.4 Credit Card Account Information <CCACCTINFO> . . . . . . . . . . . . . . . . . . . 185

11.3.5 Transfer Information <XFERINFO>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

11.3.6 Transfer Processing Status <XFERPRCSTS>. . . . . . . . . . . . . . . . . . . . . . . . . . . 188

11.4 Downloading Transactions and Balances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

11.4.1 Bank Statement Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

11.4.2 Credit Card Statement Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

11.4.3 Statement Transaction <STMTTRN>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

11.5 Statement Closing Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

11.5.1 Statement Closing Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

11.5.2 Non-Credit Card Statement <CLOSING>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

11.5.3 Credit Card Statement Closing Request <CCSTMTENDRQ> . . . . . . . . . . . . 202

11.5.4 Credit Card Statement Closing Response <CCSTMTENDRS> . . . . . . . . . . . 202

11.6 Stop Check. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

11.6.1 Stop Check Add. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

11.6.2 Status Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

11.7 Intrabank Funds Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

11.7.1 Intrabank Funds Transfer Addition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

11.7.2 Intrabank Funds Transfer Modification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

11.7.3 Intrabank Funds Transfer Cancellation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

11.8 Interbank Funds Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

11.8.1 Interbank Funds Transfer – US . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

11.8.2 Interbank Funds Transfer – International Usage . . . . . . . . . . . . . . . . . . . . . . . 220

11.8.3 Interbank Funds Transfer Modification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

11.8.4 Interbank Funds Transfer Cancellation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

11.8.5 Multiple Interbank Funds Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

11.9 Wire Funds Transfer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

11.9.1 Wire Funds Transfer Addition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

11.9.2 Wire Funds Transfer Cancellation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

OFX 1.6 Specification ix10/18/99

11.10 Recurring Funds Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

11.10.1 Recurring Intrabank Funds Transfer Addition . . . . . . . . . . . . . . . . . . . . . . . . 238

11.10.2 Recurring Intrabank Funds Transfer Modification . . . . . . . . . . . . . . . . . . . . . 242

11.10.3 Recurring Intrabank Funds Transfer Cancellation . . . . . . . . . . . . . . . . . . . . . 245

11.10.4 Recurring Interbank Funds Transfer Addition . . . . . . . . . . . . . . . . . . . . . . . . 246

11.10.5 Recurring Interbank Funds Transfer Modification . . . . . . . . . . . . . . . . . . . . . 250

11.10.6 Recurring Interbank Funds Transfer Cancellation . . . . . . . . . . . . . . . . . . . . . 253

11.11 E-Mail and Customer Notification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

11.11.1 Banking E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

11.11.2 Notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

11.11.3 Returned Check and Deposit Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

11.12 Data Synchronization for Banking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

11.12.1 Data Synchronization for Stop Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

11.12.2 Data Synchronization for Intrabank Funds Transfers. . . . . . . . . . . . . . . . . . . 262

11.12.3 Data Synchronization for Interbank Funds Transfers. . . . . . . . . . . . . . . . . . . 265

11.12.4 Data Synchronization for Wire Funds Transfers . . . . . . . . . . . . . . . . . . . . . . . 267

11.12.5 Data Synchronization for Recurring Intrabank Funds Transfers . . . . . . . . . 269

11.12.6 Data Synchronization for Recurring Interbank Funds Transfers . . . . . . . . . 271

11.12.7 Data Synchronization for Bank Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

11.13 Message Sets and Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

11.13.1 Message Sets and Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

11.13.2 Bank Message Set Profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

11.13.3 Credit Card Message Set Profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

11.13.4 Interbank Funds Transfer Message Set Profile. . . . . . . . . . . . . . . . . . . . . . . . . 290

11.13.5 Wire Transfer Message Set Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

11.14 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

11.14.1 Statement Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

11.14.2 Intrabank Funds Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

11.14.3 Stop Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

11.14.4 Recurring Transfers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Chapter 12 Payments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

12.1 Consumer and Business Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

12.2 The Payee Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

12.2.1 Payee Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

12.2.2 Payee Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

12.2.3 Standard Payee Lists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

12.2.4 Identifying Payees. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

12.2.5 Side Effects of Payee Adds and Modifications. . . . . . . . . . . . . . . . . . . . . . . . . . 315

x OFX 1.6 Specification10/18/99

12.3 Identifiers Used in Payment Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

12.4 The Payment Life Cycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

12.4.1 Payment Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

12.4.2 Payment Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

12.4.3 Payment Status Inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

12.4.4 Payment Cancellation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

12.4.5 Delayed Payee Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

12.5 Common Payments Aggregates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

12.5.1 Payments Account Information <BPACCTINFO> . . . . . . . . . . . . . . . . . . . . . 319

12.5.2 Credit Mail Order/Telephone Order Account <CCMOTOACCT> . . . . . . . 320

12.5.3 Payment Information <PMTINFO> <PMTINFO2>. . . . . . . . . . . . . . . . . . . . . 321

12.6 Payments Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

12.6.1 Payment Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

12.6.2 Payment Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

12.6.3 Payment Cancellation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

12.6.4 Payment Status Inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

12.7 Recurring Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

12.7.1 Creating a Recurring Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

12.7.2 Recurring Payment Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

12.7.3 Recurring Payment Cancellation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

12.8 Payment Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

12.8.1 Payment Mail Request and Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

12.8.2 Payment Mail Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

12.9 Payee Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

12.9.1 Adding a Payee to the Payee List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

12.9.2 Payee Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

12.9.3 Payee Deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

12.9.4 Payee List Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

12.10 Data Synchronization for Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373

12.10.1 Payment Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

12.10.2 Recurring Payment Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

12.10.3 Discussion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

12.11 Message Sets and Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

12.11.1 Bill Pay Message Sets and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

12.11.2 Bill Pay Message Set Profile <BILLPAYMSGSET> . . . . . . . . . . . . . . . . . . . . 384

12.12 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

12.12.1 Scheduling a Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

12.12.2 Modifying a Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

OFX 1.6 Specification xi10/18/99

12.12.3 Canceling a Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

12.12.4 Updating Payment Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

12.12.5 Scheduling a Recurring Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

12.12.6 Modifying a Recurring Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

12.12.7 Canceling a Recurring Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

12.12.8 Adding a Payee to the Payee List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404

12.12.9 Synchronizing Scheduled Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

Chapter 13 Investments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

13.1 Types of Response Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

13.2 Sub-Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

13.3 Units, Precision, and Signs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

13.3.1 Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

13.3.2 Precision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411

13.3.3 Signs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411

13.4 Bank and Investment Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412

13.5 Money Market Funds. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412

13.5.1 Separate Account at the Financial Institution. . . . . . . . . . . . . . . . . . . . . . . . . . . 412

13.5.2 Sweep Account Within an Investment Account . . . . . . . . . . . . . . . . . . . . . . . . 413

13.5.3 Position Within an Investment Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413

13.6 Investment Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413

13.6.1 Specifying the Investment Account <INVACCTFROM>. . . . . . . . . . . . . . . . . 413

13.6.2 Investment Account Information <INVACCTINFO>. . . . . . . . . . . . . . . . . . . . 414

13.6.3 Brokerage, Mutual Fund, and 401K Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . 415

13.7 Investment Message Sets and Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416

13.7.1 Investment Statement Download. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

13.7.2 Security Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

13.8 Investment Securities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423

13.8.1 Security Identification <SECID>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423

13.8.2 Security List Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423

13.8.3 Security List Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

13.8.4 Security List <SECLIST> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

13.8.5 Securities Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

13.9 Investment Statement Download. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

13.9.1 Investment Statement Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

13.9.2 Investment Statement Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

xii OFX 1.6 Specification10/18/99

13.10 Investment E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455

13.10.1 Investment E-Mail Request and Response . . . . . . . . . . . . . . . . . . . . . . . . . . . 455

13.10.2 Investment E-Mail Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457

13.11 Complete Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459

Chapter 14 Bill Presentment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

14.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

14.1.1 Bill Presentment Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

14.1.2 Servers and Message Sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

14.2 Biller Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466

14.2.1 Client Signon to the Biller Directory Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 466

14.2.2 Search Arguments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466

14.2.3 Identification of Bill Publishers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467

14.2.4 Find Biller Request <FINDBILLERRQ>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467

14.2.5 Find Biller Response <FINDBILLERRS>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469

14.2.6 Status Codes <FINDBILLERRS> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

14.2.7 Account Number Validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472

14.2.8 Biller Payment Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473

14.3 Customer Signup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474

14.3.1 Enrollment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

14.3.2 Account Inquiry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

14.3.3 Service Activation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479

14.3.4 Service Status Update for Groups of Customers . . . . . . . . . . . . . . . . . . . . . . . 480

14.4 Bill Delivery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484

14.4.1 Bill Delivery Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484

14.4.2 Bill List Retrieval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484

14.4.3 Bill Detail Retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498

14.4.4 Table Structure Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503

14.4.5 Delivery Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505

14.4.6 Bill Status Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508

14.5 Bill Payment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509

14.5.1 Remittance Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509

14.5.2 Payee Identification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509

14.6 Bill Presentment E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510

14.6.1 Bill Presentment Mail Request <PRESMAILRQ> . . . . . . . . . . . . . . . . . . . . . . 511

14.6.2 Bill Presentment Mail Response <PRESMAILRS>. . . . . . . . . . . . . . . . . . . . . . 511

14.6.3 Status Codes <PRESMAILRS> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512

OFX 1.6 Specification xiii10/18/99

14.6.4 Request <PRESMAILSYNCRQ> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513

14.6.5 Response <PRESMAILSYNCRS>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514

14.7 Message Sets and Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515

14.7.1 Message Sets and Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515

14.7.2 Biller Directory Message Set Profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519

14.7.3 Bill Delivery Message Set Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519

14.8 Bill Presentment Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521

14.8.1 Find Biller Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521

14.8.2 Enrollment Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528

14.8.3 Activation Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530

14.8.4 Bill Delivery Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532

Appendix A Status Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541

Appendix B Change History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549

B.1 OFX 1.0 to 1.0.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549

B.1.1 Specification Changes by Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549

B.1.2 General Specification Changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569

B.1.3 DTD Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569

B.2 OFX 1.0.1 to 1.0.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571

B.2.1 Specification Changes by Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571

B.2.2 General Specification Changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577

B.2.3 DTD Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577

B.3 OFX 1.0.2 to 1.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579

B.3.1 Specification Changes by Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579

B.4 OFX 1.5 to OFX 1.5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593

B.4.1 Specification Changes by Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593

B.4.2 DTD Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600

B.5 OFX 1.5.1 to 1.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601

B.5.1 Specification Changes by Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601

B.5.2 DTD Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621

Appendix C Recent Changes that Affect Earlier Versions . . . . . . . . . . . . . 623

C.1 Changes Made in OFX 1.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623

C.1.1 Specification Changes by Chapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623

C.2 OFX 1.5 to OFX 1.5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630

C.2.1 Specification Changes by Chapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630

C.2.2 DTD Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631

C.3 OFX 1.5.1 to 1.6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632

C.3.1 Specification Changes by Chapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632

C.3.2 DTD Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643

xiv OFX 1.6 Specification10/18/99

OFX 1.6 Specification 1510/18/99

CHAPTER 1 OVERVIEW

1.1 Introduction

Open Financial Exchange is a broad-based framework for exchanging financial data and

instructions between customers and their financial institutions. It allows institutions to connect

directly to their customers without requiring an intermediary.

Open Financial Exchange is an open specification that anyone can implement: any financial

institution, transaction processor, software developer, or other party. It uses widely accepted

open standards for data formatting (such as SGML), connectivity (such as TCP/IP and HTTP),

and security (such as SSL).

Open Financial Exchange defines the request and response messages used by each financial

service as well as the common framework and infrastructure to support the communication of

those messages. This specification does not describe any specific product implementation.

&86720(5 6

&RQVXPHUV

)DPLOLHV

7D[SD

HUV

6PDOO



%XVLQHVVHV

,167,787,216

)LQDQFLDO



,QVWLWXWLRQV

)LQD QFLDO



$GYLVRUV

*RYHUQPHQW



$JHQFLHV

0HUFKDQWV



DQG



%XVLQHVVHV

,QI R UPDWLRQ



3URYLGHUV

7UDQVDFWLRQ



3URFHVVRUV

16 1.1 Introduction

1.1.1 Design Principles

The following principles were used in designing Open Financial Exchange:

◆ Broad Range of Financial Activities – Open Financial Exchange provides support for a

broad

range of financial activities. Open Financial Exchange 1.6 specifies the following

services:

◆ Bank statement download

◆ Credit card statement download

◆ Funds transfers including recurring transfers

◆ Consumer payments, including recurring payments

◆ Business payments, including recurring payments

◆ Brokerage and mutual fund statement download, including transaction history, current

holdings, and balances.

◆ Bill presentment and payment

◆ Broad Range of Financial Institutions – Open Financial Exchange supports communication

with a

broad

range of financial institutions (FIs), including:

◆ Banks

◆ Brokerage houses

◆ Merchants

◆ Processors

◆ Financial advisors

◆ Government agencies

◆ Broad Range of Front-End Applications – Open Financial Exchange supports a

broad

range of front-end applications, including Web-based applications, covering all types of

financial activities running on all types of platforms.

◆ Extensible – Open Financial Exchange has been designed to allow the easy addition of new

services. Future versions will include support for many new services.

◆ Open – This specification is publicly available. You can build client and server applications

using the Open Financial Exchange protocols independent of any specific technology,

product, or company.

◆ Multiple Client Support – Open Financial Exchange allows a user to use multiple client

applications to access the same data at a financial institution. With the popularity of the World

Wide Web, customers are increasingly more likely to use multiple applications—either

desktop-based or Web-based—to perform financial activities. For example, a customer can

track personal finances at home with a desktop application and occasionally pay bills while at

work with a Web-based application. The use of data synchronization to support multiple

clients is a key innovation in Open Financial Exchange.

OFX 1.6 Specification 1710/18/99

◆ Robust – Open Financial Exchange will be used for executing important financial

transactions and for communicating important financial information. Assuring users that

transactions are executed and information is correct is crucial. Open Financial Exchange

provides robust protocols for error recovery.

◆ Secure – Open Financial Exchange provides a framework for building secure online financial

services. In Open Financial Exchange, security encompasses authentication of the parties

involved, as well as secrecy and integrity of the information being exchanged.

◆ Batch & Interactive – The design of request and response messages in Open Financial

Exchange is for use in either batch or interactive style of communication. Open Financial

Exchange provides for applying a single authentication context to multiple requests in order

to reduce the overhead of user authentication.

◆ International Support – Open Financial Exchange is designed to supply financial services

throughout the world. It supports multiple currencies, country-specific extensions, and

different forms of encoding such as UNICODE.

◆ Platform Independent –Open Financial Exchange can be implemented on a wide variety of

front-end client devices, including those running Windows 3.1, Windows 95, Windows NT,

Macintosh, or UNIX. It also supports a wide variety of Web-based environments, including

those using HTML, Java, JavaScript, or ActiveX. Similarly on the back-end, Open Financial

Exchange can be implemented on a wide variety of server systems, including those running

UNIX, Windows NT, or OS/2.

◆ Transport Independent – Open Financial Exchange is independent of the data

communication protocol used to transport the messages between the client and server

computers. Open Financial Exchange 1.0.2, 1.5.1, and 1.6 use HTTP.

18 1.2 Open Financial Exchange at a Glance

1.2 Open Financial Exchange at a Glance

The design of Open Financial Exchange is as a client and server system. An end-user uses a client

application to communicate with a server at a financial institution. The form of communication

is requests from the client to the server and responses from the server back to the client.

Open Financial Exchange uses the Internet Protocol (IP) suite to provide the communication

channel between a client and a server. IP protocols are the foundation of the public Internet and a

private network can also use them.

1.2.1 Data Transport

Clients use the HyperText Transport Protocol (HTTP) to communicate to an Open Financial

Exchange server. The World Wide Web throughout uses the same HTTP protocol. In principle, a

financial institution can use any off-the-shelf web server to implement its support for Open

Financial Exchange.

To communicate by means of Open Financial Exchange over the Internet, the client must

establish an Internet connection. This connection can be a dial-up Point-to-Point Protocol (PPP)

connection to an Internet Service Provider (ISP) or a connection over a local area network that

has a gateway to the Internet.

Clients use the HTTP POST command to send a request to the previously acquired Uniform

Resource Locator (URL) for the desired financial institution. The URL presumably identifies a

Common Gateway Interface (CGI) or other process on an FI server that can accept Open

Financial Exchange requests and produce a response.

OFX 1.6 Specification 1910/18/99

The POST identifies the data as being of type application/x-ofx. Use application/x-ofx as the

return type as well. Fill in other fields per the HTTP 1.0 specification. Here is a typical request:

POST http://www.fi.com/ofx.cgi HTTP/1.0

HTTP headers

User-Agent:MyApp 5.0

Content-Type: application/x-ofx

Content-Length: 1032

OFXHEADER:100

OFX headers

DATA:OFXSGML

VERSION:160

SECURITY:TYPE1

ENCODING:USASCII

CHARSET:NONE

COMPRESSION:NONE

NEWFILEUID:NONE

OLDFILEUID:NONE

<OFX>

OFX request

... Open Financial Exchange requests ...

</OFX>

A blank line defines the separation between the HTTP headers and the start of the Open

Financial Exchange headers. A blank line also separates the Open Financial Exchange headers

and the request. (See Chapter 2, “Structure” for more information about the Open Financial

Exchange headers.) A brief note here that a “blank line” means a carriage return and a linefeed

pair – CRLF.

The structure of a response is similar to the request, with the first line containing the standard

HTTP result, as shown next. The content length is given in bytes.

HTTP 1.0 200 OK

HTTP headers

Content-Type: application/x-ofx

Content-Length: 8732

OFXHEADER:100

OFX headers

DATA:OFXSGML

VERSION:160

SECURITY:TYPE1

ENCODING:USASCII

CHARSET:NONE

COMPRESSION:NONE

NEWFILEUID:NONE

OLDFILEUID:NONE

<OFX>

OFX response

... Open Financial Exchange responses ...

</OFX>

20 1.2 Open Financial Exchange at a Glance

1.2.2 Request and Response Model

The basis for Open Financial Exchange is the request and response model. One or more requests

can be batched in a single file. This file typically includes a signon request and one or more

service-specific requests. An FI server will process all of the requests and return a single response

file. This batch model lends itself to Internet transport as well as other off-line transports. Both

requests and responses are plain text files, formatted using a grammar based on Standard

Generalized Markup Language (SGML). Open Financial Exchange is syntactically similar to

HyperText Markup Language (HTML), featuring tags to identify and delimit the data. The use of

a tagged data format allows Open Financial Exchange to evolve over time while continuing to

support older clients and servers.

Here is a simplified example of an Open Financial Exchange request file. (This example does not

show the Open Financial Exchange headers and the indentation is only for readability.) For

complete details, see the more complete examples throughout this specification.

<USERPASS>MyPassword

</FI>

<APPID>MyApp

<APPVER>0500

</SONRQ>

</SIGNONMSGSRQV1>

<TRNUID>1001

<ACCTTYPE>CHECKING

</BANKACCTFROM>

OFX 1.6 Specification 2110/18/99

</INCTRAN>

</STMTRQ>

</STMTTRNRQ>

</BANKMSGSRQV1>

</OFX>

The response format follows a similar structure. Although a response, such as a statement

response, contains all of the details of each transaction, each individual detail of the statement is

identified using tags.

The key rule of Open Financial Exchange syntax is that each tag is either an element or an

aggregate. Data follows its element tag. An aggregate tag begins a compound tag sequence,

which must end with a matching tag; for example, <AGGREGATE> ... </AGGREGATE>.

The file sent by Open Financial Exchange does not require any white space between tags.

White space following a tag delimiter (>), following an element value, or preceding a tag

delimiter (<) should be ignored. White space within an element value (i.e. not preceding, not

following) is significant. If white space is desired preceding or following an element value, this is

achieved using the CDATA wrapper or, in version 2 message sets and Bill Presentment, the

&nbsp macro. If more than one white space element is needed, then multiple &nbsp macros

should be utilized. See section 2.3.2.1

1.3 Definitions

The following sections detail definitions that hold within the context of OFX.

1.3.1 User

User refers to the person or entity interfacing with the OFX client to cause it to generate OFX

requests.

1.3.2 Financial Institution

Financial Institution (FI) refers to the institution with which the user has a direct relationship.

Generally this means a bank, but in many cases it may be an institution providing non-banking

financial services.

1.3.3 Service Provider

Service Provider (SP) refers to an institution with which the user does not have a direct

relationship. Generally, such an institution is subcontracted by the FI to provide specific services

to the customer on behalf of the FI.

22 1.3 Definitions

1.3.4 Client

An OFX client is the software that generates OFX requests, receives responses and processes them.

This may be a personal finance manager, a web browser running locally interactive code (such as

with a Java applet or ActiveX control), a Web server, a proxy, or one of many other possibilities.

1.3.5 Server

An OFX server is the software that receives OFX requests, processes them, and generates OFX

responses.

1.3.6 Service

A service is a collection of related transactions. For example, the BANKSVC service encompasses

banking transactions such as requesting bank statements, initiating stop checks, initiating wire

transfers, etc.

In OFX 1.x, services are used directly only when describing or changing the general options

available to a particular customer. Other collections of transactions instead use the concept of

Message Sets as described in section 1.3.15

1.3.7 Tag

Tag is the generic name for either a start tag or an end tag. A start tag consists of an element or

aggregate name surrounded by angle brackets. An end tag is the same as a start tag, with the

addition of a forward slash immediately preceding the name. For example, the start tag for the

aggregate named FOO looks like this:

<FOO>

The end tag for the same aggregate looks like this:

</FOO>

OFX 1.6 Specification 2310/18/99

1.3.8 Element

An OFX document contains one or more elements. An element is some data bounded by a leading

start tag and a trailing end tag, end of the containing aggregate or start of the next element. For

example, an element named BAZ, containing data “bar,” could look like this:

or:

<BAZ>bar</FOO><!-- An element ended by the required end tag of the

aggregate that contains it -->

or:

<BAZ>bar<DIFFER>something<!An element ended by the start tag of the

following element -->

Note that this definition differs slightly from the SGML definition of element, in that an OFX

element must contain data (not just white space) and may not contain other elements. Elements

in OFX are optional wherever the content might otherwise be missing. An SGML element

containing other elements is defined in OFX as an aggregate. OFX specifically disallows empty

elements and elements with mixed content.

With the exception of <MSGBODY> and <EXTDPMTDSC>, end tags are optional for all OFX

elements.

1.3.9 Aggregate

An aggregate is a collection of elements and/or other aggregates. An aggregate may not contain

any data itself, but rather contains elements containing data, and/or recursively contains

aggregates.

OFX includes very few empty aggregates and clients and servers should not send an aggregate

without content. In general, the entire aggregate should be left out of a request or response file

when its (optional) content is missing. The few exceptions to these rules (such as <SECLISTRS>,

described in section 13.8.3.3

) are called out in the relevant sections of this document.

End tags are required for all OFX aggregates.

24 1.3 Definitions

1.3.10 Request

A request is information sent by the client. An OFX request file is the entire SGML file sent by the

client, including the OFX headers. An individual request generally is an aggregate whose name

ends in RQ.

1.3.11 Response

A response is information sent by the server. An OFX response file is the entire SGML file sent by

the server, including the OFX headers. An individual response generally is an aggregate whose

name ends in RS.

When elements and aggregates from the request also appear in the corresponding response they

are generally intended to echo the values from a request in the response (this enables client

matching with the request, for example). While the server should not modify data in individual

elements when echoing, elements not found in a particular request may be added in the

response. These situations (such as adding a <PAYEELSTID> when creating a <PMTRQ>

response) are described as they arise. OFX also includes a few specific situations requiring

different information to be sent and returned in corresponding elements of a request/response

pair. Again, these exceptions (such as the <TOKEN> element in a sync request and response) are

described as they arise.

1.3.12 Message

A message is the unit of work in OFX. It refers to a request and response pair. For example, the

message to download a bank statement consists of the request <STMTRQ> and the response

<STMTRS>.

1.3.13 Transaction

A transaction consists of a message and its associated transaction wrappers. The transaction

request wrapper contains a unique transaction identifier used to prevent ambiguity in matching

a particular response to its associated request, and the request aggregate. The transaction

response wrapper contains a status aggregate, the transaction identifier sent in the request, and

(if the transaction was successful) the response aggregate. For details on the use of transaction

wrappers, see section 2.4.6

1.3.14 Synchronization

For messages subject to synchronization (see Chapter 6, "Data Synchronization"), an added layer

of aggregates is also part of a message definition: a synchronization request and response. These

add a token and, in some cases, other information. Synchronization requests may encapsulate

embedded transactions that execute only when certain conditions are true at the server (either the

OFX 1.6 Specification 2510/18/99

containing synchronization request completed without error or the request had no errors and the

client was up to date).

1.3.15 Message Set

Message sets are collections of messages. Generally they form all or part of a service (as defined in

section 1.3.6

). OFX utilizes these smaller groupings when wrapping request or response

transactions, profiling server support for the wrappers and describing individual messages. The

BANKSVC service, for example, is broken into the BANKMSGSET, CREDITCARDMSGSET,

INTERXFERMSGSET and WIREXFERMSGSET message sets.

Please refer to section 2.4.5 , "

Message Sets and Version Control" for additional information

about message sets.

1.4 OFX Versions

This document specifies three distinct versions of OFX clients and servers.

Version 1.0.2 supports any or all version 1 message sets except Bill Presentment. These message

sets are defined by the OFX 1.0.2 Document Type Definition (DTD), which is used for parsing.

Applications that conform to this version are referred to as 1.0.2 clients and 1.0.2 servers.

Version 1.5.1 supports all version 2 message sets, Bill Presentment, and all version 1 message

sets. Because it supports all message sets, the OFX 1.5.1 DTD can be used to create and support

OFX 1.0.2 and/or OFX 1.5.1 clients and servers.

Version 1.6 DTD supports all message sets available in the OFX 1.5.1 DTD. It adds specific

enhancements to some of the aggregates. All of those enhancements are optional and should not

be used by a client unless the server indicates support in its FI Profile. Applications that conform

to this version are referred to as 1.6 clients and 1.6 servers. The OFX 1.6 DTD fully incorporates

the OFX 1.0.2 and 1.5.1 message sets, so it can be used to support both 1.0.2 and 1.5.1

applications.

For a complete description of OFX message sets, see section 2.4.5.3

As of the publication of this document, only versions 1.0.2, 1.5.1, and 1.6 of OFX are supported.

This document completely describes the supported OFX versions. Other, previous versions and

documents (specifications and errata) are obsolete. For a list of changes between versions, see

Appendix B, "

Change History."

26 1.5 Conventions

1.5 Conventions

The conventions used in the element and aggregate descriptions include the following:

◆ Required elements and aggregates are in bold. Regular face indicates elements and

aggregates that are optional. Required means that a client must always include the element or

aggregate in a request, and a server must always include the element or aggregate in a

response.

◆ Required elements and aggregates occur once unless noted as one or more in the description,

in which case the specification allows multiple occurrences.

◆ Optional elements and aggregates occur once if present unless noted as zero or more in the

description, in which case the specification allows multiple occurrences.

◆ Character fields are identified with a data type of “A-n”, where n is the maximum number of

allowed Unicode characters.

Note: n refers to the number of characters in the resultant string. Each multi-byte or

encoded character counts as a single character. UTF-8 encodes “high” Latin-1

characters (decimal 128-255) using two bytes, and double-byte characters using three

bytes. In addition, SGML encodes ampersands, less-than symbols, greater-than

symbols, and spaces (where required) using multi-character escape strings (see section

2.3.2.1). Therefore, an element of type A-40 may require more than 40 bytes in a UTF-

8-encoded SGML stream.

◆ N-n identifies an element of numeric type where n is the maximum number of characters in

the value. Values of this type are generally whole numbers, but the data type allows negative

numbers. OFX includes a few fixed-position numeric values (such as <APPVER>, see section

2.5.1.1

) called out in the text. In all cases, elements of this type may contain only the characters

0 through 9 and - (hyphen, the negative sign indicator). So an element of type “N-6” may take

values from -99999 to 999999. The value “0000000” would be illegal for an N-6 element. White

space is not allowed within the numeric value. Leading zeroes are allowed, but discouraged

except where noted in the text. For example, a <MIN> element containing zero might be sent

as “<MIN>0”, “<MIN>00”, “<MIN> 0", but not “<MIN>0 0".

◆ Common value types, such as a dollar amount, are referenced by name. Chapter 3, "Common

Aggregates, Elements, and Data Types" lists value types that are referenced by name.

◆ In some aggregates, there are different elements and aggregates used in different message set

versions. In those aggregates, there is a third column in the table, called Version. In that

column, for any elements and aggregates that differ across message set versions, there is a

description of the difference. For example, many elements and aggregates say “V2 only” to

indicate that they are in message set version 2 only. Features added with OFX 1.6 are

annotated “1.6 add” and should be requested only when the server indicates support for that

feature in its FI Profile (see Chapter 7, "

FI Profile"). Most “1.6 add” features (all but

<REFRESHSUPT>, see section 7.2.1

) are also “V2 only” or part of the new

<PRESDLVMSGSETV1>.

OFX 1.6 Specification 2710/18/99

◆ Explanatory information is in italics

Tag Version Description

Required element or aggregate (1 or more)

Required element or aggregate that occurs

only once

<OPTIONAL> Optional element or aggregate; this

element or aggregate can occur multiple

times (0 or more)

<SPECIFIC> Values are A, B, and C

<ALPHAVALUE> Takes a value up to 32 characters in length,

A-32

<NEW> V2 only Element or aggregate used only in version

2 of this message set

<NEW2> 1.6 add Element or aggregate should be used only

when the server indicates support for this

option in its FI Profile (see

Chapter 7, "FI

Profile"). Most “1.6 add” features (all but

<REFRESHSUPT>, see section

7.2.1) are

also “V2 only” or part of the new

<PRESDLVMSGSETV1>.

Explanatory text Hopefully useful information.

28 1.5 Conventions

OFX 1.6 Specification 2910/18/99

CHAPTER 2 STRUCTURE

This chapter describes the basic structure of an Open Financial Exchange request and response.

Structure includes headers, basic syntax, and the Signon request and response. This chapter also

describes how Open Financial Exchange encodes external data, such as bit maps.

Open Financial Exchange data consists of some headers plus one Open Financial Exchange data

block. This block consists of a signon message and zero or more additional messages. When sent

over the Internet using HTTP, standard HTTP and (optionally) multipart MIME headers and

formats surround the Open Financial Exchange data. A simple file that contained only Open

Financial Exchange data would have the following form:

HTTP headers

MIME type application/x-ofx

Open Financial Exchange headers

Open Financial Exchange SGML block

A more complex file that contained additional Open Financial Exchange data would have this

form:

HTTP headers

MIME type multipart/x-mixed-replace; boundary =XYZZY24x7

--XYZZY24x7

MIME type application/x-ofx

Open Financial Exchange headers

Open Financial Exchange SGML block

--XYZZY24x7

MIME type image/jpeg

FI logo

--XYZZY24x7--

Version 1.0.2 of the Open Financial Exchange specification did not specify how to properly

separate the various components of an OFX request. In particular, separation of the HTTP

headers, the MIME attachments, the OFX headers, the OFX header elements, and the OFX SGML

block.

OFX 1.0.2 clients used a mix of LF and CRLF constructs and OFX 1.0.2 servers handled either

linefeed (LF) or carriage return/line feed (CRLF), but not often both. In the future, it is expected

that 1.0.2 servers will be upgraded to handle both CRLF and LF.

In version 1.5 and later of the Open Financial Exchange specification, the behavior for both an

OFX client and an OFX server has been specified to encourage uniform usage of the

specification.

OFX 1.6 Client

A proper client should separate the components of an OFX request using a single CRLF between

each component. A proper request thus has the form:

OFX 1.6 Server

An OFX 1.6 specification server should expect OFX request components and elements to be

separated by the appropriate number of CRLF characters. However, as per W3C

recommendations, an OFX 1.6 server should also accept just a LF as a separator. This behavior is

as per the recommendation of the World Wide Web Consortium (W3C). The W3C is the

worldwide standards body for web technology.

http://www.w3.org

(W3C home page)

http://www.w3.org/Protocols/HTTP/OldClients.html

(W3C recommendations)

HTTP headers

CRLF(s)

MIME type information

CRLF(s)

OFX header element 1

CRLF

OFX header element 2

CRLF

OFX header element n

CRLF(s)

OFX SGML Block

OFX 1.6 Specification 3110/18/99

The text has been included below for ease of reference:

2.1 HTTP Headers

Data delivered by way of HTTP places the standard HTTP result code on the first line. HTTP

defines a number of status codes. Servers can return any standard HTTP result. However, FIs

should expect clients to collapse these codes into the following three cases:

Note: The server must return a code in the 400s for any problem that prevents it from

processing the request file. Processing problems include failures relating to security,

communication, parsing, or the Open Financial Exchange headers (for example, the

client requested an unsupported language). For content errors such as wrong

USERPASS or invalid account, the server must return a valid Open Financial

Exchange response along with code 200. If a communication time-out error occurs

while an OFX server and a back-end server are communicating to fill a request, then

the server MUST return a code in the 500s.

Code Meaning Action

200 OK The request was processed and a valid Open Financial Exchange result is

returned.

400s Bad request The request was invalid and was not processed. Clients will report an

internal error to the user. Invalid requests include: general HTTP

transport errors, SGML formatting errors, invalid OFX syntax, and

invalid data values. This error should not appear for request files the

server is able to parse.

500s Server error The server is unavailable. Clients should advise the user to retry shortly.

Note: Server tolerance of bad clients.

Whilst it is seen appropriate for testing parsers to check full conformance to this

specification, it is recommended that operational parsers be tolerant of deviations.

In particular, lines should be regarded as terminated by the Line Feed, and the

preceding Carriage Return character ignored.

Any HTTP Header Field Name which is not recognized should be ignored in

operational parsers.

It is recommended that servers use URIs free of “variant” characters whose

representation differs in some of the national variant character sets, punctuation

characters, and spaces. This will make URIs easier to handle by humans when the need

(such as debugging, or transmission through non-hypertext systems) arises.

32 2.2 Open Financial Exchange Headers

Open Financial Exchange requires the following HTTP standard headers:

When responding with multipart MIME (likely only if the request included a <GETMIMERQ>

request), the main type will be multipart/x-mixed-replace; one of the parts will use application/

x-ofx.

2.2 Open Financial Exchange Headers

The contents of an Open Financial Exchange file consist of a simple set of headers followed by

contents defined by that header

The Open Financial Exchange headers are in a simple element:value syntax and terminated by a

blank line. Open Financial Exchange always sends headers unencrypted, even if application-

level encryption is used for the remaining contents. The language and character set used for the

headers is the same as the preceding MIME headers.

The first entry will always be OFXHEADER with a version number. This entry identifies the

contents as an Open Financial Exchange file and provides the version number of the Open

Financial Exchange headers that follow (not the version number of the contents). For example:

OFXHEADER:100

Open Financial Exchange headers can contain the following elements.

DATA:OFXSGML

VERSION:160

SECURITY:

ENCODING:

CHARSET:

COMPRESSION:

OLDFILEUID:

NEWFILEUID:

All OFX headers are required. NONE should be returned if client or server does not make use of

an individual element, e.g., COMPRESSION:NONE, OLDFILEUID:NONE

Code Value Explanation

Content-

type

application/

x-ofx

The MIME type for Open Financial Exchange

Content-

length

length Length of the data after removing HTTP headers

OFX 1.6 Specification 3310/18/99

A blank line follows the last header. Then (for type OFXSGML), the SGML-readable data begins

with the <OFX> tag.

For information about each of the OFX headers, refer to the following sections.

2.2.1 OFXHEADER

OFXHEADER specifies the version number of the Open Financial Exchange headers.

The OFXHEADER value change its major number only if an existing client is unable to process

the new header. This can occur because of a complete syntax change in a header, or a significant

change in the semantics of an existing header element.

The current version of the Open Financial Exchange headers is version 1.0 (OFXHEADER:100).

2.2.2 DATA

DATA specifies the content type, in this case OFXSGML.

The value of the DATA element changes only when an entirely new syntax is introduced. In the

case of OFXSGML, a new syntax would have to be non-SGML compliant to warrant a new

DATA value. It is possible that there will be more than one syntax in use at the same time to meet

different needs.

2.2.3 VERSION

VERSION specifies the version number of the Document Type Definition (DTD) used for

parsing. The are currently three supported DTDs:

◆ The OFX 1.0.2 DTD supports all version 1 message sets, except Bill Presentment. It can be

used to create and support OFX 1.0.2 clients and servers.

◆ The OFX 1.5.1 DTD supports all version 2 message sets, Bill Presentment, and all version 1

message sets. Because it supports all message sets, the OFX 1.5.1 DTD can be used to create

and support OFX 1.0.2 and/or OFX 1.5.1 clients and servers.

◆ The OFX 1.6 DTD supports all message sets available in the OFX 1.5.1 DTD. It adds specific

enhancements to some of the aggregates. All of those enhancements are optional and should

not be used by a client unless the server indicates support in its FI Profile. The OFX 1.6 DTD

can be used to create and support OFX 1.0.2 through OFX 1.6 clients and servers.

The current accepted values for VERSION are 102, 151, and 160.

Note: VERSION provides the version number of the DTD. The message set

aggregates within the <OFX> block describes the version numbers of specific message

sets. See section 2.4.5.3

34 2.2 Open Financial Exchange Headers

2.2.4 SECURITY

SECURITY defines the type of application-level security, if any, that is used for the <OFX> block.

The values for SECURITY can be NONE or TYPE1.

For more information about security, refer to Chapter 4, "

OFX Security."

2.2.5 ENCODING and CHARSET

ENCODING defines the text encoding used for character data. The values for ENCODING can

be USASCII or UTF-8.

CHARSET defines the character set used for character data. The values for CHARSET may be

ISO-8859-1 (Latin-1), 1252 (Windows Latin-1), or NONE. Any value specified here is likely to be

ignored by an OFX client or server.

For more information about ENCODING and CHARSET, refer to Chapter 5, "

International

Support."

2.2.6 COMPRESSION

A future version of the specification will define compression.

2.2.7 OLDFILEUID and NEWFILEUID

NEWFILEUID uniquely identifies this request file. The NEWFILEUID, which clients must send

with every request file and which servers must echo in the response, serves two purposes:

◆ Servers can use the NEWFILEUID to quickly identify duplicate request files.

◆ Clients and servers can use NEWFILEUID in conjunction with OLDFILEUID for file-based

error recovery. For more information about using file-based error recovery or lite

synchronization, see Chapter 6, "

Data Synchronization."

OLDFILEUID is used together with NEWFILEUID only when the client and server support file-

based error recovery. OLDFILEUID identifies the last request and response that was received

and processed by the client.

OFX 1.6 Specification 3510/18/99

2.3 SGML Details

2.3.1 Compliance

SGML is the basis for Open Financial Exchange. A DTD formally defines the SGML wire format

for Open Financial Exchange. However, Open Financial Exchange is not completely SGML-

compliant because the specification allows unrecognized tags to be present. Clients and servers

must skip over the unrecognized tags. In this context, an “unrecognized tag” includes existing

(well known) tags used in a new location. Clients and servers must ignore all such tags in order

to allow future revisions to the specification and private tags which don’t require profile control.

That is, if a client or server does not recognize <XYZ>, it must ignore the tag and its enclosed

data. A fully compliant SGML parser would not validate a document that contains tags that the

DTD does not define.

Although SGML is the basis for the specification, and the specification is largely compliant with

SGML, do not assume Open Financial Exchange supports any SGML features not documented in

this specification.

2.3.2 Valid SGML Characters

Open Financial Exchange elements can be set to any sequence of SGML characters. To be valid, a

value must contain at least one character that is not a blank character. In other words, a value

cannot contain only white space.

2.3.2.1 Special Characters

For the purposes of Open Financial Exchange, a few characters must be handled as special

characters. To represent a special character, use the corresponding escape sequence.

Note: The space macro was not added until OFX 1.5. So when using a version 1

message set (excluding Bill Presentment), there may be both clients and servers that

can not process the   syntax. In this case, you must prefix strings containing

space characters as the first or last characters with “<![CDATA[”and suffix them with

“]]>.” See Chapter 9, "

Customer to FI Communication," for an example.

Character Version Escape sequence

< (less than) <

> (greater than) >

& (ampersand) &

‘ ‘ (space) V2 only  

36 2.4 Open Financial Exchange SGML Structure

Note: Space characters in the middle of a value do not require use of the special

character macro. If a string value needs to contain space characters as the first or last

characters, that’s when this macro is needed.

For example, the string “AT&T” encodes “AT&T.”

Note: Escape sequences are not required when these special characters are used in

element values that accept HTML-formatted strings (for instance, e-mail records).

These elements accept SGML-marked section syntax that hides the HTML from the

Open Financial Exchange parser. You must prefix the HTML-formatted strings with

“<![CDATA[”and suffix them with “]]>.” Within these bounds, treat the above

characters literally without an escape. See Chapter 9, "

Customer to FI

Communication," for an example.

2.3.3 Comments Not Supported

For explanatory purposes, the examples in this specification contain comments. However, Open

Financial Exchange files cannot contain comments.

2.4 Open Financial Exchange SGML Structure

2.4.1 Overview

Open Financial Exchange hierarchically organizes request and response blocks:

Top Level <OFX>

Message Set and Version <

xxx

MSGSVn>

Synchronization Wrappers <

xxx

SYNCRQ>, <

xxx

SYNCRS>

Transaction Wrappers <

xxx

TRNRQ>, <

xxx

TRNRS>

Specific requests and responses

The following sections describe these levels.

2.4.2 Case Sensitivity

OFX requires upper case letters for tag names and enumerated values. In the example below,

<SEVERITY> is an element with an enumerated value and <MESSAGE> is an element with a

value that is not enumerated.

<CODE> 2000

<SEVERITY> ERROR

<MESSAGE> General Error

</STATUS>

OFX 1.6 Specification 3710/18/99

2.4.3 Top Level

An Open Financial Exchange request or response has the following top-level form:

This chapter specifies the order of requests and responses.

A single file MUST contain only one OFX block.

2.4.4 Messages

A message is the unit of work in Open Financial Exchange. It refers to a request and response

pair, and the status codes associated with that response. For example, the message to download a

bank statement consists of the request <STMTRQ> and the response <STMTRS>.

OFX uses several common message types to perform specific functions. Within OFX, the

following naming conventions are used, where the general xxx messages may be:

◆ Basic (or Add) request <xxxRQ> and response <xxxRS>

◆ Modify request <xxxMODRQ> and response <xxxMODRS>

◆ Delete request <xxxDELRQ> and response <xxxDELRS>

◆ Cancel request <xxxCANRQ> and response <xxxCANRS> (these pairs may also be named

<xxxCANCRQ> and <xxxCANCRS)

Tag Description

<OFX>

Opening tag

<SONRQ> or

<SONRS>

Required signon request or response. See section 2.5.1.

... Open Financial

Exchange requests or

responses ...

0 or more transaction requests and responses inside appropriate message

set aggregates

</OFX>

Closing tag for the Open Financial Exchange record

38 2.4 Open Financial Exchange SGML Structure

2.4.4.1 Basic and Add Messages

The basic OFX message has a name structure of <xxxRQ>/<xxxRS>. It is used for read actions of

a specific object (such as a bank statement using <STMTENDRQ>). It is encapsulated in a

transaction wrapper <xxxTRNRQ> or <xxxTRNRS> (therefore, <STMTENDTRNRQ> and

<STMTENDTRNRS> in the example above).

The add OFX message, like the Basic message, has a name structure of <xxxRQ>/<xxxRS>. It is

used to create a new instance of object xxx (such as creating a new payment using <PMTRQ>). It

is encapsulated in a transaction wrapper <xxxTRNRQ> or <xxxTRNRS> (therefore

<PMTTRNRQ> and <PMTTRNRS> in the example above).

2.4.4.2 Modify Message

The modify OFX message has a name structure of <xxxMODRQ>/<xxxMODRS>. It is used to

modify an existing instance of object xxx (such as modifying an existing payment using

<PMTMODRQ>). It is encapsulated in a transaction wrapper <xxxTRNRQ> or <xxxTRNRS>

(therefore, <PMTTRNRQ> and <PMTTRNRS> in the example above).

The <xxxMODRQ> request contains the complete replacement data for an existing object xxx.

Therefore, both changed and unchanged elements must be included in the request.

2.4.4.3 Delete and Cancel Messages

The delete and cancel OFX messages have a name structure of <xxxDELRQ>/<xxxDELRS> and

<xxxCANRQ>/<xxxCANRS> or <xxxCANCRQ>/<xxxCANCRS>, respectively. They are used

to delete an existing instance of object xxx (such as deleting a payee from a payee list using

<PAYEEDELRQ>), or to cancel an existing scheduled object (such as canceling a pending

payment using <PMTCANCRQ>). They are encapsulated in a transaction wrapper

<xxxTRNRQ> or <xxxTRNRS> (therefore, <PAYEETRNRQ> and <PMTTRNRQ> in the

examples above).

2.4.4.4 Inquiry Message

The inquiry OFX message sometimes has a name structure of <xxxINQRQ>/<xxxINQRS>. It is

used to search for and/or gain information about (an) existing object(s) xxx (such as finding one

or more existing payments using <PMTINQRQ>). It is encapsulated in a transaction wrapper

<xxxINQTRNRQ> or <xxxINQTRNRS> (therefore, <PMTINQTRNRQ>and <PMTINQTRNRS>

in the example above).

Inquiry messages limit the response set to records matching the selection criteria used in the

request. Selection criterion elements in the request are generally repeating elements. Where more

than one value is given for a particular element, the query ORs those values. Where multiple

different elements (matches for different fields of the objects) are provided, the query ANDs

those values. Where an element is absent from the request, the query is not filtering on that

OFX 1.6 Specification 3910/18/99

element. If an element has a history associated with it, only the most recent value is intended by

the inquiry.

Note: A server is not obligated to support filtering on all selection criterion elements.

If a server chooses not to support a particular element as a selection criterion, it must

treat that element as if it were not present. That is, the server must return the

appropriate record set for the elements on which it does support filtering. As a result,

clients should be prepared to receive records outside the scope of the selection criteria

submitted in the request.

Note: Many inquiry messages do not presently follow the naming conventions

detailed above. They may be named <xxxINFORQ>/<xxxINFORS>

(<ACCTINFORQ> and <ACCTINFORS> for example) or without reference to an

obvious convention (<PRESLISTRQ> and <PRESLISTRS> for example).

2.4.5 Message Sets and Version Control

Message sets are collections of messages. Generally they form all or part of what a user would

consider a service, something for which they might have signed up, such as “banking.” Message

sets are the basis of version control, routing, and security. They are also the basis for the required

ordering in Open Financial Exchange files.

Within the OFX block, OFX organizes messages by message set. Message sets follow these rules:

◆ With the exception of <SIGNUPMSGSRQV2>, a request file may include at most one message

set wrapper of each type.

The one exception to this rule is <SIGNUPMSGSRQV2>. The <SIGNUPMSGSRQV2>

message sets may repeat as often as required. Each repetition of the <SIGNUPMSGSRQV2>

message set wrappers must have differing top-level elements (for example, different

<USERID> values in OFX 1.6).

In addition, repetitions of <SIGNUPMSGSRSV2> must be ordered to match the

<SIGNUPMSGSRQV2> wrappers in the request file (each <USERID> must be returned in

the same order).

◆ For a particular service, the V1 and V2 message sets may not be combined in a single request

file.

For example, the <SIGNUPMSGSRQV1> and SIGNUPMSGSRQV2> message set wrappers

must not appear together in a request file.

◆ All messages within any message set must be from the same version of that message set.

◆ Servers must respond using the same message sets and versions as sent in the request file. For

example, if <SIGNUPMSGSRQV1> appears in the request file, <SIGNUPMSGSRSV1> must

appear in the response file. And, if <BANKMSGSRSV2> was not in the request file,

<BANKMSGSRQV2> must not appear in the response.

40 2.4 Open Financial Exchange SGML Structure

There are two exceptions to this rule:

◆ Servers may ignore unsupported message set wrappers.

◆ Servers may return the <SECLISTMSGSRSVn> wrapper (see 13.7.2 and 13.8.4) in response

to an investment statement download (with or without a <SECLISTMSGSRQVn> in the

request file).

2.4.5.1 Message Set Aggregates

For each message set of xxx and version n, there are two aggregates, one for requests

<xxxMSGSRQVn>) and one for responses <xxxMSGSRSVn>. All of the messages from that

message set must be enclosed in the appropriate message set aggregate. In the following

example, the Open Financial Exchange block contains a signon request inside the signon

message set, and two statement requests and a transfer request inside the bank message set.

<OFX>

...

</SONRQ>

</SIGNONMSGSRQV1>

...

</STMTTRNRQ>

...

</STMTTRNRQ>

...

</INTRATRNRQ>

</BANKMSGSRQV1>

</OFX>

OFX 1.6 Specification 4110/18/99

2.4.5.2 Message Set Ordering

Message sets must appear in the following order:

◆ Signon

◆ Signup

◆ Banking

◆ Credit card statements

◆ Investment statements

◆ Interbank funds transfers

◆ Wire funds transfers

◆ Payments

◆ General e-mail

◆ Investment security list

◆ Biller Directory

◆ Bill Delivery

◆ FI Profile

The definition of each message set can further prescribe an order of its messages within that

message set.

For ordering purposes, versions of a message set are grouped with the message set. For instance,

Signon V2 would precede Banking V1, using the “natural” ordering above.

2.4.5.3 Message Set Version Numbers

Message sets have their own version numbers, which are distinct from the version numbers of

the Open Financial Exchange headers and the Document Type Definition (DTD) files.

Note: OFX versions 1.5.1 and 1.6 are intended to interoperate without problems. The

additions made in OFX 1.6 are optional and may be ignored by 1.5.1 clients and

servers without complications.

In particular, a server must indicate support for a new

feature before a client may use that feature.

The version numbers of the Open Financial

Exchange headers and the Document Type Definition (DTD) files appear in the Open

Financial Exchange headers, before the <OFX> data block. For more information

about the Open Financial Exchange headers, see section 2.2. The current version

number of the headers is OFXHEADER: 100. The current version numbers of the

DTDs are 102, 151, and 160.

42 2.4 Open Financial Exchange SGML Structure

The following table lists each message set, along with its aggregate name and the DTD versions

that support it.

Note: For each message set that it is supporting, a financial institution must indicate

which version numbers of that message set it supports. The financial institution

includes the message set version number in the <MSGSETCORE> aggregate of the FI

profile. For more information about the FI profile, refer to Chapter 7, "

FI Profile."

Message Set Message Set Aggregate DTD Support

Signon <SIGNONMSGSETV1> 1.0.2, 1.5.1, 1.6

Signon <SIGNONMSGSETV2> 1.5.1, 1.6

Signup <SIGNUPMSGSETV1> 1.0.2, 1.5.1, 1.6

Signup <SIGNUPMSGSETV2> 1.5.1, 1.6

Banking <BANKMSGSETV1> 1.0.2, 1.5.1, 1.6

Banking <BANKMSGSETV2> 1.5.1, 1.6

Credit Card Statements <CREDITCARDMSGSETV1> 1.0.2, 1.5.1, 1.6

Credit Card Statements <CREDITCARDMSGSETV2> 1.5.1, 1.6

Investment Statements <INVSTMTMSGSETV1> 1.0.2, 1.5.1, 1.6

Investment Statements <INVSTMTMSGSETV2> 1.5.1, 1.6

Interbank Funds Transfers <INTERXFERMSGSETV1> 1.0.2, 1.5.1, 1.6

Interbank Funds Transfers <INTERXFERMSGSETV2> 1.5.1, 1.6

Wire Funds Transfers <WIREXFERMSGSETV1> 1.0.2, 1.5.1, 1.6

Wire Funds Transfers <WIREXFERMSGSETV2> 1.5.1, 1.6

Payments <BILLPAYMSGSETV1> 1.0.2, 1.5.1, 1.6

Payments <BILLPAYMSGSETV2> 1.5.1, 1.6

General e-mail <EMAILMSGSETV1> 1.0.2, 1.5.1, 1.6

General e-mail <EMAILMSGSETV2> 1.5.1, 1.6

Investment security list <SECLISTMSGSETV1> 1.0.2, 1.5.1, 1.6

Investment security list <SECLISTMSGSETV2> 1.5.1, 1.6

Biller directory <PRESDIRMSGSETV1> 1.5.1, 1.6

Bill delivery <PRESDLVMSGSETV1> 1.5.1, 1.6

FI Profile <PROFMSGSETV1> 1.0.2, 1.5.1, 1.6

FI Profile <PROFMSGSETV2> 1.5.1, 1.6

OFX 1.6 Specification 4310/18/99

2.4.6 Transactions

Other than the signon message, each request is made as a transaction. Transactions contain a

client-assigned globally-unique ID, optional client-supplied pass-back data, and the request

aggregate. A transaction similarly wraps each response. The response transaction returns the

client ID sent in the request, along with a status message, the pass-back data if present, and the

response aggregate. This technique allows a client to track responses against requests. Section

3.1.2

provides more information about the format of information exchanged by the client and

server.

The <STATUS> aggregate, defined in Chapter 3, "

Common Aggregates, Elements, and Data

Types," provides feedback on the processing of the request. If the <SEVERITY> of the status is

ERROR, the server provides the transaction response without the nested response aggregate.

Otherwise, the response must be complete even though some warning might have occurred.

Clients can send additional information in <CLTCOOKIE> that servers will return in the

response. This allows clients that do not maintain state, and thus do not save <TRNUID>s, to

cause some additional descriptive information to be present in the response. For example, a

client might identify a request as relating to a user or a spouse.

Starting with the message sets new to OFX 1.5 and later (e.g., the V2 message sets and the bill

presentation message sets), <CLTCOOKIE> must only be returned by the server in the initial

response to the client (and any crash recovery from that response). The <CLTCOOKIE> should

not be present in a sync response, except for those transactions whose requests were wrapped in

the sync request. This restriction is new for message set version 2 of all the message sets.

In some countries, some banks may require that a customer-supplied authorization number be

included to authenticate certain kinds of individual transactions such as payment requests. For

those banks, the <TAN> element passes this information to servers.

Note that if a <CLTCOOKIE> is given to an OFX server in a request, the OFX server is required

to return it. This return of the <CLTCOOKIE> will necessitate server-side storage of

<CLTCOOKIE> data. In the case of an OFX client getting a <CLTCOOKIE> that it didn’t send in

a request, the default behavior is to ignore it.

44 2.4 Open Financial Exchange SGML Structure

2.4.6.1 Transaction Wrapper

With the exception of the <SONRQ>/<SONRS> message, each message has a corresponding

transaction wrapper. For requests, the transaction wrapper adds a transaction unique ID

<TRNUID>. For responses, the transaction wrapper adds the same transaction unique ID

<TRNUID> (an echo of that found in the request), plus a <STATUS> aggregate.

The transaction wrapper has a name structure of <xxxTRNRQ>/<xxxTRNRS>. A transaction

wrapper pair encapsulates a single message (<xxxRQ>/<xxxRS>, <xxxMODRQ>/

<xxxMODRS>, etc.).

While the same name may be used for addition, modification and deletion messages, a single

transaction wrapper may contain at most one request or response. The request transaction

wrapper must contain a single request. The response transaction wrapper must contain a single

response unless the contained <STATUS> aggregate indicates an error. The

<MULTIINTERTRNRQ>/<MULTIINTERTRNRS> pair (section 11.8.5) is an exception to these

rules.

Note: Some requests and responses (generally, Add, Modify, and Delete/Cancel

types) share a transaction wrapper and synchronization wrapper. In these cases, the

names of the transaction and synchronization wrappers reflect the Add message.

A typical request is as follows:

Tag Description

xxx

TRNRQ>

Transaction-request aggregate

Client-assigned globally-unique ID for this transaction, trnuid

Data to be echoed in the transaction response, A-32

<TAN>

Transaction authorization number; used in some countries with some types of

transactions. The FI Profile defines messages that require a <TAN>, A-80

Request

aggregate

Aggregate for the request

xxx

TRNRQ>

OFX 1.6 Specification 4510/18/99

A typical response is as follows:

List of status code values for the <CODE> element of <STATUS>:

2.4.7 Synchronization Wrapper

The synchronization wrapper has a name structure of <xxxSYNCRQ>/<xxxSYNCRS>. It contains

synchronization parameters and optionally encapsulates one or more transaction wrappers. For

details on the use of synchronization wrappers, see Chapter 6.

When embedded transactions are not present, the synchronization request contains no

transaction wrappers. If the client is up to date when the server processes such a request, the

synchronization response also contains no transaction wrappers.

Note: If a request/response is a sync request/response only, the transaction wrapper

and request that it wraps are omitted.

Tag Version Description

xxx

TRNRS>

Transaction-response aggregate

Client-assigned globally-unique ID for this transaction, trnuid

Status aggregate

</STATUS>

V2 change Client-provided data, REQUIRED if provided in request, A-32

See note above regarding usage inside sync response.

Response

aggregate

Aggregate for the response

xxx

TRNRS>

Value Meaning

0 Success (INFO)

2000 General error (ERROR)

2022 Invalid TAN (ERROR)

46 2.5 The Signon Message Set

2.4.8 Message Set Wrapper

The profile message set wrappers have a name structure of <xxxMSGSET>, <xxxMSGSETV1> and

<xxxMSGSETV2>. The “V1” and “V2” variants always appear inside a <xxxMSGSET> wrapper.

They correspond to the supported version of the message set under consideration.

The request and response message set wrappers have a name structure of <xxxMSGSRQVn> and

<xxxMSGSRSVn> respectively. For OFX 1.6 and earlier, “n” must be either “1” or “2”. This

number indicates the version of the message set used by the contained messages.

2.5 The Signon Message Set

The Signon message set includes the signon message, USERPASS change message, and challenge

message, which must appear in that order. The <SIGNONMSGSRQV1> and

<SIGNONMSGSRSV1> (also V2) aggregates wrap the message.

2.5.1 Signon <SONRQ> <SONRS>

The signon record identifies and authenticates a user to an FI. It also includes information about

the application making the request, because some services might be appropriate only for certain

clients. Every Open Financial Exchange block contains exactly one <SONRQ>. Every response

must contain exactly one <SONRS> record. Use of Open Financial Exchange presumes that FIs

authenticate each customer and then give the customer access to one or more accounts or

services. Authentication of a <SONRQ> is required, even when in Error Recovery. If passwords

are specific to individual services or accounts, a separate Open Financial Exchange request must

be made for each user ID or password required. This will not necessarily be in a manner visible

to the user. Note that some situations, such as joint accounts or business accounts, will have

multiple user IDs and multiple passwords that can access the same account.

FIs assign user IDs for the customer. Although the user ID may be the customer’s social security

number, the client must not make any assumptions about the syntax of the ID, add check-digits,

or do similar processing.

To improve server efficiency in handling a series of Open Financial Exchange request files sent

over a short period of time, clients can request that a server return a <USERKEY> in the signon

response. If the server provides a user key, clients will send the <USERKEY> instead of the user

ID and password in subsequent sessions, until the <USERKEY> expires. This allows servers to

authenticate subsequent requests more quickly. Servers must accept a <GENUSERKEY> element

in a <SONRQ>. However, a server may decide <USERKEY> does not afford sufficient security

and may optionally not return a <USERKEY> in the <SONRS>.

The client returns <SESSCOOKIE> if the server sent one in a previous <SONRS>. Servers can use

the value of <SESSCOOKIE> to track client usage but cannot assume that all requests come from

a single client, nor can they deny service if they did not expect the returned cookie. Use of a

OFX 1.6 Specification 4710/18/99

backup file, for example, could lead to an unexpected <SESSCOOKIE> value that nevertheless

should not stop a user from connecting.

A client may use an anonymous form of <USERID> and <USERPASS> on those rare occasions

when a server need not authenticate the <SONRQ>. The only present situations in this class are

first-time <PROFRQ>, <FINDBILLERRQ>, and all <ENROLLRQ> transactions. Any request

sent by the client after a successful <ENROLLRQ> response (or out of band enrollment) for the

service must provide the user’s <USERID> and <USERPASS>. The anonymous <USERID> or

<USERPASS> value is left aligned and padded with 0 to a length of 32 characters:

anonymous00000000000000000000000

Note: This anonymous password length may exceed the <MAX> value for the profile

server (in the corresponding <SIGNONINFO> aggregate). Nonetheless, servers

supporting anonymous signon must not reject this password due to its length.

Servers can request that a consumer change his or her password by returning status code 15000.

Servers should keep in mind that only one status code can be returned. If the current signon

response status should be 15500 (invalid ID or password), the request to change the password

must wait until an otherwise successful signon is achieved.

If the server returns any signon error, it must respond to all other requests in the same <OFX>

block with status code 15500. For example, if the server returns status code 15502 to the signon

request, it must return status code 15500 to all other requests in the same <OFX> block. The

server must return status code 15500 to all requests; it cannot simply ignore the requests.

An OFX 1.5.1 or greater server has the option of allowing or disallowing “empty” signon

transactions. In the context of signon, “empty” means a simple signon without any other

transaction (a sync, statement download, etc.). If the OFX 1.5.1 or greater server does not support

empty signon, it should return error 15506. If the OFX 1.5.1 or greater server does support empty

signon, it should process the signon and return the appropriate error or success code.

For OFX 1.0.2 servers, it is optional whether or not to support error 15506. Since additional error

codes can be added to an OFX 1.0.2 server, it is suggested that logic to support error 15506 be

added to OFX 1.0.2 servers that wish to disallow empty signon transactions. Older clients should

remap unknown error codes to a general error.

If the server returns any signon error, it must respond to all other requests in the same <OFX>

block with status code 15500. For example, if the server returns status code 15502 to the

<SONRQ> request, it must return status code 15500 to all other requests in the same <OFX>

block. The server must return status code 15500 for all requests; it cannot simply ignore the

requests. In addition, any sync responses must indicate an error with <TOKEN>–1,

<LOSTSYNC>N (<LOSTSYNC> is an optional element) and (in version 2 responses) an

appropriate <SYNCERROR>. Responses for any transactions embedded in the sync request

should contain the same <STATUS><CODE>15500. Otherwise, they must be omitted from the

sync response wrapper. (See section 6.2 for data synchronization specifics.)

48 2.5 The Signon Message Set

2.5.1.1 Signon Request <SONRQ>

Unlike other requests, the signon request <SONRQ> does not appear within a transaction

wrapper.

Tag Version Description

<SONRQ>

Signon-request aggregate

Date and time of the request from the client computer, datetime

This value should reflect the time (according to the client machine)

when the request file is sent to the server, not the (original) creation

time of the request file. While not required for existing software,

OFX 1.6 clients must comply with this rule. This clarification is

particularly important in error recovery situations in which the

request file may be sent to the server after its initial creation.

User identification.

Either <USERID> and

<USERPASS> or

<USERKEY>, but not

both.

User identification string, A-32

User password on server, A-171

Note: The maximum clear text length of USERPASS is 32

characters: a client must not send a longer password. However,

when using Type 1 security, the encrypted value may extend to 171

characters.

V2 only A special type of password that is used only once (in addition to

USERPASS) to authenticate a single OFX session, A-32

Note: The client can send this element only if the <PWTYPE>

value returned by the server is ONETIME or HWTOKEN (See

section 7.2.2

-or-

Request server to return a USERKEY for future use, Boolean

Requested language for text responses, language

V2 only Specific country system used for the requests in this <OFX> block:

3-letter country code from ISO/DIS-3166.

If this element is not present, the country system is USA.

The following countries are currently supported in OFX:

OFX 1.6 Specification 4910/18/99

COUNTRY

BEL

CAN

CHE

DEU

ESP

FRA

GBR

ITA

NLD

USA

Country Name

Belgium

Canada

Switzerland

Germany

Spain

France

Great Britain

Italy

Netherlands

United States of America

<FI>

Financial-Institution-identification aggregate

Note: The client will determine out-of-band whether a FI

aggregate should be used and if so, the appropriate values for it. If

the FI aggregate is to be used, then the client should send it in every

request, and the server should return it in every response.

</FI>

Session cookie value received in previous <SONRS>, not sent if first

<APPID>

ID of client application, A-5

Version of client application, (6.00 encoded as 0600), N-4

</SONRQ>

Tag Version Description

50 2.5 The Signon Message Set

2.5.1.2 Signon Response <SONRS>

Unlike other responses, the signon response <SONRS> does not appear within a transaction

wrapper.

Note: In several V2 message sets, the specific definition of an element is dependent

upon the <COUNTRY> element in <SONRS>. For example, when using the V2

version of the Banking message set, BANKID of the BANKACCTFROM aggregate is

interpreted depending on the value of COUNTRY (see section 11.3.1

). If a server wants

to prevent potential client ambiguity regarding the country system being used, the

server should require Signon Message Set V2.

Note: A client should use <DTPROFUP> and <DTACCTUP> only when the service

provider that originated <SONRS> is the same provider that is specified by

<SPNAME> in the profile message set. A client can determine if the service provider is

the same by comparing the value of <SPNAME> in the appropriate message set with

the value for <SPNAME> in the profile message set.

Tag Version Description

<SONRS>

Record-response aggregate

Status aggregate, see section 3.1.5. See list of possible code values

in section 2.5.1.3

</STATUS>

Date and time of the server response, datetime

This value should reflect the time (according to the server) when

the response file was originally created. While not required for

existing software, OFX 1.6 servers must comply with this rule.

This clarification is particularly important in error recovery

situations: The server should (must for OFX 1.6 servers) return

the time the request was first processed. If the previous attempt

failed after transactions were processed, <DTSERVER> in the

response file would reflect that processing time.

Use user key instead of USERID and USERPASS for subsequent

requests. TSKEYEXPIRE can limit lifetime. A-64

Date and time that USERKEY expires, datetime

Language used in text responses, language

OFX 1.6 Specification 5110/18/99

V2 only Specific country system used for the requests: 3-letter country

code from ISO/DIS-3166.

If this element is not present, the country system is USA.

Note: Where element behaviors are listed within this

specification as dependent upon the value of <COUNTRY>, the

reference is to this one in the <SONRS> aggregate. It is not to be

confused with the element <COUNTRY> that appears elsewhere

in OFX, associated with addresses.

Date and time of last update to profile information for any service

supported by this FI (see Chapter 7, "

FI Profile"), datetime

Date and time of last update to account information (see Chapter

8, “Activation & Account Information”), datetime

<FI>

Financial-Institution-identification aggregate

Note: The client will determine out-of-band whether an FI

aggregate should be used and, if so, the appropriate values for it.

If the FI aggregate is to be used, then the client should send it in

every request, and the server should return it in every response.

</FI>

Session cookie that the client should return on the next

<SONRQ>,A-1000

</SONRS>

Tag Version Description

52 2.5 The Signon Message Set

2.5.1.3 Status Codes

List of status code values for the <CODE> element of <STATUS>:

Value Meaning

0 Success (INFO)

2000 General error (ERROR)

13504 <FI> Missing or Invalid in <SONRQ> (ERROR)

15000 Must change USERPASS (INFO)

15500 Signon invalid (see section 2.5.1

) (ERROR)

15501 Customer account already in use (ERROR)

15502 USERPASS Lockout (ERROR)

15505 Country system not supported by server (ERROR)

15506 Empty signon transaction not supported (ERROR)

15507 Signon invalid without supporting pin change request (ERROR)

OFX 1.6 Specification 5310/18/99

2.5.1.4 Financial Institution ID <FI>

Some service providers support multiple FIs, and assign each FI an ID. The signon allows clients

to pass this information along, so that providers know to which FI the user is signing on.

If a server does not require an FI aggregate in a request but receives one anyway, it should echo

the FI aggregate back. This is compliant with the general rule that the server should echo

elements and aggregates in the response if they are received and understood in the request.

If a server requires the <FI> aggregate in <SONRQ> requests and it contains incorrect

information there are several different specification compliant ways to respond. These are given

in the order of preference:

◆ Return a 2000 error with appropriate text message – since the FI aggregate information is

incorrect the user’s information (<USERID> and <USERPASS>) cannot be verified. Returning

a 15500 might cause clients to display messages to the user that the attempt to communicate

with the server failed. A client would probably suggest that the user verify their <USERID>

and <USERPASS> values.

◆ Return a 15500 error – since the FI aggregate information is incorrect or unknown the server

cannot verify the <USERID>, <USERPASS>, etc.

◆ Return an http 400 error – this is the least desirable option since it will provide no useful

feedback to the client communicating with the server, however it is legal.

Tag Description

<FI>

FI-record aggregate

<ORG>

Organization defining this FI name space, A-32

<FID>

Financial Institution ID (unique within <ORG>), A-32

</FI>

54 2.5 The Signon Message Set

2.5.2 USERPASS Change <PINCHRQ> <PINCHRS>

The client sends a request to change the customer password as a separate request from the

signon. The transaction request <PINCHTRNRQ> aggregate contains <PINCHRQ>. Responses

are placed inside the transaction response <PINCHTRNRS>.

Password changes pose a special problem for error recovery. If the client does not receive a

response, it cannot know whether or not the password change was successful. OFX recommends

that servers accept either the old password or the new password on the connection following the

one containing a password change. When file-based error recovery is in use, the server must

reject the old password except when received with NEWFILEUID/OLDFILEUID headers

indicating an error recovery attempt.

Servers that do not support file-based error recovery (or, when interacting with a client that does

not utilize file-based error recovery) must not complete a <PINCHRQ> until after the next

request file arrives. If that request file uses the new password, the new password must be

permanently associated with the <USERID>. Otherwise, the old password may authenticate the

user. (For security, servers may return a signon error if the next request file uses the old password

but does not include a <PINCHRQ>.) Conforming clients should re-send request files

(unchanged beyond the <SONRQ>) after a failure whether or not file-based error recovery is in

use.

2.5.2.1 <PINCHRQ>

A USERPASS change request changes the customer’s password for the specific realm associated

with the messages contained in the OFX block. Based on the properties of an OFX profile,

defined in Chapter 7, "

FI Profile," a single OFX block contains instructions related to a single

realm. The USERPASS change request thus changes the USERPASS for all message sets

associated with one realm. For more information about signon realms, see section 7.2.2

Tag Description

USERPASS-change-request aggregate

User identification string. Often a social security number, but if so, does not

include any check digits, A-32

Note: The maximum clear text length of USERPASS is 32 characters: a

client must not send a longer password. However, when using Type 1

security, the encrypted value may extend to 171 characters.

New user password, A-171

Note: The effective size of NEWUSERPASS is A-32. However, if Type 1

security is used, then the actual field length is A-171.

</PINCHRQ>

OFX 1.6 Specification 5510/18/99

2.5.2.2 <PINCHRS>

2.5.2.3 Status Codes

Note: If On Behalf Of is not allowed for the signed-on user, status code 15508 may

result from a <USERID> mismatch between the <SONRQ> and <PINCHRQ>. For

information about On Behalf Of actions, see section 8.1.1

Tag Description

USERPASS-change-response aggregate

User identification string. Often a social security number, but if so, does not

include any check digits, A-32

Date and time the password was changed, datetime

</PINCHRS>

Value Meaning

0 Success (INFO)

2000 General error (ERROR)

15503 Could not change USERPASS (ERROR)

15508 Transaction not authorized (ERROR)

56 2.5 The Signon Message Set

2.5.3 <CHALLENGERQ> <CHALLENGERS>

A challenge request is the first step in Type 1 application-level security. Essentially, it asks for

some random data from the server. The challenge response provides that server-generated

random data and is the second step in Type 1 security.

The challenge message is part of the signon message set and is not subject to data

synchronization.

2.5.3.1 <CHALLENGERQ>

A <CHALLENGERQ> is part of a <CHALLENGETRNRQ> transaction, a <CHALLENGERS>

part of a <CHALLENGETRNRS>.

The client includes <FICERTID> in the request if it already has the server’s certificate. If it’s

included and matches the server’s current certificate, the server may omit the actual certificate

from the response.

2.5.3.2 <CHALLENGERS>

When generating the <NONCE>, make sure the data is as unpredictable as possible. See RFC

1750 for recommendations.

The server includes <FICERTID> in the response to identify the certificate in a separate MIME

part. Even if the certificate itself is not attached, <FICERTID> is still included in the response.

Tag Description

Opening tag for the challenge request.

User identification string, A-32

Optional server certificate ID. A-64

</CHALLENGERQ>

Closing tag for challenge request.

Tag Description

Opening tag for the challenge response.

User identification string, A-32

<NONCE>

Server-generated random data. A-16

ID of server certificate used to encrypt. A-64

</CHALLENGERS>

Closing tag for challenge response.

OFX 1.6 Specification 5710/18/99

2.5.3.3 Status Codes

Status code values for the <CODE> element of <STATUS>:

2.5.4 Signon Message Set Profile Information

A server must include the signon message set <SIGNONMSGSET> as part of the

<MSGSETLIST> aggregate in the FI profile, since every server must support signon requests.

The information that is part of the <MSGSETCORE> aggregate (for example, the URL and

security level) is used only when no other message sets are used. Otherwise, the other message

sets override the signon message set for the purposes of batching and routing. For example, if

bill payments are sent to a URL that is different from the one used for signon, the client uses the

URL specified in the bill payment message set <BILLPAYMSGSET>. For more information about

how clients batch and route messages, refer to section 7.1.3

Value Meaning

0 Success (INFO)

2000 General error (ERROR)

15504 Could not provide random data (ERROR)

15508 Transaction not authorized (ERROR)

Tag Description

Signon-message-set-profile-information aggregate

Opening tag for V1 of the message set profile information

Common message set information, defined in Chapter 7, "FI Profile"

</MSGSETCORE>

</SIGNONMSGSETV1>

Opening tag for V2 of the message set profile information

Common message set information, defined in Chapter 7, "FI Profile"

</MSGSETCORE>

</SIGNONMSGSETV2>

</SIGNONMSGSET>

58 2.6 External Data Support

2.5.5 Examples

User requests a password change:

<TRNUID>888

<USERID>123456789

<NEWUSERPASS>5321

</PINCHRQ>

</PINCHTRNRQ>

The server responds with:

<TRNUID>888

<CODE>0

<SEVERITY>INFO

</STATUS>

<USERID>123456789

</PINCHRS>

</PINCHTRNRS>

2.6 External Data Support

Some data, such as binary data, cannot easily be sent within SGML. For these situations, the

specification defines an element that references some external data. The way that clients pick up

the external data depends on the transport used. For the HTTP-based transport described in this

document, servers can send the data in one of two ways:

◆ Send the same response, using multipart MIME types to separate the response into the Open

Financial Exchange file and one or more external data files

◆ Client can make a separate HTTP get against the supplied URL, if it really needs the data

For example, to retrieve a logo, a <GETMIMERS> might answer a <GETMIMERQ> as follows:

<URL>https://www.fi.com/xxx/yyy/zzz.jpg

</GETMIMERS>

If the file includes the same response using multipart MIME, clients must have the local file,

zzz.jpg.

OFX 1.6 Specification 5910/18/99

2.7 Extensions to Open Financial Exchange

An organization that provides a customized client and server that communicate by means of

Open Financial Exchange might wish to add new requests and responses or even specific

elements to existing requests and responses. To ensure that each organization can extend the

specification without the risk of conflict, Open Financial Exchange defines a style of tag naming

that lets each organization have its own name space.

Organizations can register a specific tag name prefix. (The specific procedure or organization to

manage this registration will be detailed at a later time.) If an organization registers “ABC,” then

they can safely add new elements and aggregates named <ABC.SOMETHING> without

◆ Colliding with another party wishing to extend the specification

◆ Confusing a client or server that does not support the extension

The extensions are not considered proprietary. An organization is free to publish their extensions

and encourage client and server implementors to support them.

All tag names that do not contain a period (.) are reserved for use in future versions of the Open

Financial Exchange specification.

60 2.7 Extensions to Open Financial Exchange

OFX 1.6 Specification 6110/18/99

CHAPTER 3 COMMON AGGREGATES, ELEMENTS, AND

DATA TYPES

3.1 Common Aggregates

This section describes aggregates used in more than one service of Open Financial Exchange (for

example, investments and payments).

3.1.1 Identification of Financial Institutions and Accounts

Open Financial Exchange does not provide a universal space for identifying financial

institutions, accounts, or types of accounts. The way to identify an FI and an account at that FI

depends on the service. For information about service-specific ID aggregates, see Chapter 11,

"Banking," Chapter 12, "Payments," and Chapter 13, "Investments."

3.1.2 Format of User-Supplied Numbers

Clients and proxies (or, other intermediate OFX servers) should not attempt to add or remove

punctuation from user-supplied values. This information should be transmitted without change

to the OFX server. Examples of elements that may contain punctuation significant to the server

are <ADDR1>, <EMAIL>, and any of the <xxxPHONE> elements found in the specification.

In some cases, clients may use additional information (not available to the customer) to enhance

user-supplied text. An <ACCTFORMAT> or <ACCTEDITMASK> (including required

punctuation characters, for example) may be used to normalize an entered <ACCTID> (say,

containing only numbers) into the format needed by the server. Or, the <POSTALCODE> in a US

address may be extended to include the full ZIP+4 value. These cases of client manipulation of

user-supplied values are not common in the OFX specification. For example, a client that

removes all punctuation from a user-supplied phone number is compliant with the requirements

but not the intent of the OFX specification.

When matching user-supplied text against stored information, servers are free to ignore all

supplied punctuation characters. For example, a server might remove all punctuation from an

<ACCTID> before performing validation. This temporary modification affects neither how the

data would be returned nor its storage format. Such transformations should not occur with

values provided for security reasons such as <USERID> and <USERPASS> elements. These

transformations (relaxed matches between selection criteria and saved data) are required only for

<TAXID> in an enrollment request and the <BANKID> and <ACCTID> elements of the

<xxxACCTTO> aggregate. Otherwise, exact matches of selection criteria and saved data are all

that is required by this specification.

62 3.1 Common Aggregates

Servers are permitted to add or remove punctuation or otherwise modify client-supplied

information, while storing the data after processing a (successful) <xxxRQ> or <xxxMODRQ>

request. For example, a server might store only the first five digits of a US <POSTALCODE>

value, abbreviate common address components (storing “St.” when the request specified

“Street”), or use a special address for well-known payees. If a server does make such

modifications, it must return the client-supplied values verbatim in the initial response, and treat

the modification as a server-initiated action. Therefore, a subsequent synchronization should

include a <xxxMODRS> with the server-stored values and <TRNUID>0 (zero) to indicate that

the server modified the client-supplied values.

This last requirement does not distinguish between insignificant changes (case or abbreviations)

and semantic differences (use of a completely different address for well-known payees).

Although it is recommended that clients be notified of all insignificant storage discrepancies and

modifications, it is required that clients be informed of all other such modifications.

In some cases, for security reasons, a server will not accept a value that is punctuated differently

than expected. In this case, punctuation must conform to an expected format.

3.1.3 Echoing in Responses

A server should echo back unedited element values in the immediate response, but may store

values in edited form. In the cases where the stored value is changed, it is recommended that the

server respond with an out-of-band modification synchronization response whenever possible.

For example, if a client sends a payee name of “Sears” but the server stores it as “SEARS”, the

server should send a <PAYEEMODRS> in the next sync response. (See Chapter 12, "

Payments"

for clarification of payee issues.) However, if the server simply edits punctuation in or out of

client-supplied numbers such as account numbers and will match both forms in future requests,

it is not required to notify the client.

Any intermediate software should avoid any modifications to these values, thus avoiding the

need to resolve this issue out-of-band.

OFX 1.6 Specification 6310/18/99

3.1.4 Balance Records <BAL>

Several responses allow FIs to send an arbitrary set of balance information as part of a response,

for example a bank statement download. FIs might want to send information on outstanding

balances, payment dates, interest rates, and so forth. Balances can report the date the given

balance reflects in <DTASOF>.

Tag Description

<BAL>

Balance-response aggregate

<NAME>

Balance name, A-32

<DESC>

Balance description, A-80

Balance type.

DOLLAR = dollar (value formatted DDDD.cc)

PERCENT = percentage (value formatted XXXX.YYYY)

NUMBER = number (value formatted as is)

<VALUE>

Balance value.

Interpretation depends on <BALTYPE> field, amount

Effective date of the given balance, datetime

If dollar formatting, can optionally include currency

</CURRENCY>

</BAL>

64 3.1 Common Aggregates

3.1.5 Error Reporting <STATUS>

To provide as much feedback as possible to clients and their users, Open Financial Exchange

defines a <STATUS> aggregate. The most important element is the code that identifies the error.

Each response defines the codes it uses. Codes 0 through 2999 have common meanings in all

Open Financial Exchange transactions. Codes from 3000 and up have meanings specific to each

transaction.

Clients should assume the burden of checking the profile and not sending a transaction which

the server does not support. If the client goes ahead and sends such a transaction, the server

must ignore unrecognized and unsupported elements and aggregates within a request.

Assuming no other problems occur in processing that request, servers may return warning code

2028 (Request element unknown). In either case (an unrecognized transaction or unknown

elements or aggregates within a request), the response file should not contain the unrecognized

tags or the contents of unrecognized aggregates.

The last 200 error codes in each assigned range of 1000 are reserved for server-specific status

codes. For example, of the general status codes, 2800-2999 are reserved for status codes defined

by the server. Of the banking status codes, codes 10800-10999 are reserved for the server. If a

client receives a server-specific status code of <SEVERITY> ERROR that it does not know, it must

handle it as a general error 2000.

Tag Version Description

Error-reporting aggregate.

<CODE>

Error code, N-6

Severity of the error:

INFO = Informational only

WARN = Some problem with the request occurred but a valid

response still present

ERROR = A problem severe enough that response could not

be made

V1 only A textual explanation from the FI. Note that clients will

generally have messages of their own for each error ID. Use

this element only to provide more details or for the general

errors. A-255

V2 only A textual explanation from the FI. Note that clients will

generally have messages of their own for each error ID. Use

this element only to provide more details or for the general

errors. A-2000

</STATUS>

OFX 1.6 Specification 6510/18/99

For general errors, the server can respond with one of the following <CODE> values. However,

not all codes are possible in a specific context.

Note: Clients will generally have error messages that are based on <CODE>.

Therefore, do not use <MESSAGE> to replace that text. Use <MESSAGE> only to

explain an error not well described by one of the defined codes, or to provide some

additional information. <MESSAGE> should be returned whenever the <CODE> can

be refined. For example, <CODE>2000 should always be accompanied with a

<MESSAGE> explaining the problem.

3.2 Common Elements

This section defines elements used in several services of Open Financial Exchange. The format of

the value is either character (A-n) or numeric (N-n) with a maximum length n; or as a named

type. Section 3.2.8

describes the named types.

3.2.1 Client-Assigned Transaction UID <TRNUID>

Format: A-36

Open Financial Exchange uses <TRNUID>s to identify transactions within transaction wrappers

(<xxxTRNRQ>, </xxxTRNRQ>).

In most cases, clients originate <TRNUID>s. When a client originates a <TRNUID>, the value of

the <TRNUID> is always set to a unique identifier. The server must return the same <TRNUID>

in the corresponding response and any later synchronization responses that include this

response. Clients may use this <TRNUID> to match up requests and responses or to recognize

synchronized responses for transactions they did not initiate. Servers can use <TRNUID>s to

reject duplicate requests. Because multiple clients might be generating requests to the same

server, transaction IDs must be unique across clients. Thus, <TRNUID> must be a globally

unique ID.

Code Meaning

0 Success (INFO)

2000 General error (ERROR)

Note: Servers should provide a more specific error whenever possible. Error

2000 should be reserved for cases in which a more specific code is not available.

2021 Unsupported version (ERROR)

2028 Requested element unknown (WARNING)

6502 Unable to process embedded transaction due to out-of-date <TOKEN> (ERROR)

15500 Signon invalid (See section 2.5.1)

(ERROR)

66 3.2 Common Elements

In some cases, servers can originate a transaction that was not specifically requested by a client.

For instance, a client might set up a recurring payment model. Although the client originates the

payment model, the server originates the individual payments. Whenever the server originates a

transaction, the value of the <TRNUID> must be set to zero. Lite synchronization servers (see

Chapter 6, "Data Synchronization") must respond to synchronization requests with information

about all changes of this type.

The Open Software Foundation Distributed Computing Environment standards specify a 36-

character hexadecimal encoding of a 128-bit number and an algorithm to generate it. Clients are

free to use their own algorithm, to use smaller <TRNUID>s, or to relax the uniqueness

requirements. However, it is RECOMMENDED that clients allow for the full 36 characters in

responses to work better with other clients.

For example: A client creates a new recurring payment using <RECPMTRQ> in a

<RECPMTTRNRQ> with <TRNUID>123. Later, the same client might cancel the model using

<RECPMTCANRQ> in a <RECPMTTRNRQ> with <TRNUID>456. The server would inform the

client of any spawned payments using <PMTRS> responses with <TRNUID>0 in later payment

synchronization responses (<PMTSYNCRS>).

Usage: All services

3.2.2 Server-Assigned ID <SRVRTID>, <SRVRTID2>

Format: A-10 for <SRVRTID>, used in V1 message sets; A-36 for <SRVRTID2>, used in V2 message

sets

A <SRVRTID> is a server-assigned ID for an object that is stored on the server. It should remain

constant throughout the lifetime of the object on the server. The client will consider the SRVRTID

as its “receipt” or confirmation and will use this ID in any subsequent requests to change, delete,

or inquire about this object.

A <SRVRTID> is not unique across FI’s or Service Providers, and clients might need to use FI +

<SPNAME> + <SRVRTID> when a unique key is necessary.

Where the context allows, a server may use the same value for a given server object for both

<SRVRTID> and <FITID>, but the client will not know this. In this case, the server must assign

<SRVRTID> and <FITID> values that are more unique than otherwise required. Because of the

differing uniqueness constraints on the individual elements, such a reused value must be unique

throughout the FI.

For example: The server creates the new recurring model from the example in section 3.2.1

with

<RECSRVRTID>1234:5687:1234. The server uses this identifier in the initial <RECPMTRS> and

any synchronization responses that reference this model. The client references the same

<RECSRVRTID> in the later <RECPMTCANRQ>.

OFX 1.6 Specification 6710/18/99

If any payments are spawned from this model before it is cancelled, they would each have their

own <SRVRTID> value (for example, <SRVRTID>8765:4321:8765 and

<SRVRTID>1234:5678:1234). The <SRVRTID> value for one of the spawned payments may

match the <RECSRVRTID> of the model. Such a match is not required for any spawned

payment. To guarantee uniqueness of the payment identifiers, no more than one spawned

payment may use the <RECSRVRTID> value of its model.

Usage: Payments, Banking

Elements of this type: PAYEEID2, PAYEELSTID2, RECSRVRTID, RECSRVRTID2, SRVRTID, and

SRVRTID2

3.2.3 Financial Institution Transaction ID <FITID>

Format: A-255

An FI (or its Service Provider) assigns an <FITID> to uniquely identify a financial transaction

that can appear in an account statement. Its primary purpose is to allow a client to detect

duplicate responses. Open Financial Exchange intends <FITID> for use in statement download

applications, where every transaction (not just those that are client-originated or server-

originated) requires a unique ID.

An <FITID> also uniquely identifies the closing statement in <CLOSINGRS> and

<CCCLOSINGRS>. Again, the OFX client should detect repeated closing statements (duplicate

downloads) using these identifiers.

FITIDs must be unique within the scope of the requested transactions (that is, within an account)

but need not be sequential or even increasing. Clients should be aware that FITIDs are not

unique across FIs. If a client performs the same type of request within the same scope at two

different FIs, clients will need to use FI + <ACCTID> + <FITID> as a globally unique key in a

client database. That is, the <FITID> value must be unique within the account and Financial

Institution (independent of the service provider).

Note: Although the specification allows FITIDs of up to 255 characters, client

performance may significantly improve if servers use fewer characters. It is

recommended that servers use 32 characters or fewer.

For example: The two spawned payments mentioned in section 3.2.1

are processed and later

downloaded in a <STMTRS>. The first payment’s <STMTTRN> would list

<SRVRTID>8765:4321:8765, <RECSRVRTID>1234:5678:1234, and <FITID>9999:8888:7777. The

second payment would be described in a <STMTTRN> containing <SRVRTID>1234:5678:1234,

<RECSRVRTID>1234:5687:1234, and <FITID>6666:5555:4444.

Usage: Bank statement download, investment statement download

Elements of this type: <CORRECTFITID>, <FITID>, <RELFITID>, and <REVERSALFITID>

68 3.2 Common Elements

3.2.4 Token <TOKEN>, <TOKEN2>

Format: A-10 for <TOKEN>, used in V1 message sets; A-36 for <TOKEN2>, used in V2 message sets

Open Financial Exchange uses <TOKEN> as part of data synchronization requests to identify the

point in history that the client has already received data, and in responses to identify the server’s

current end of history. See Chapter 6, “Data Synchronization,” for more information.

<TOKEN> is unique within an FI and the scope of the synchronization request. For example, if

the synchronization request includes an account ID, the <TOKEN> needs to be unique only

within an account. Servers are free to use a <TOKEN> that is unique across the entire FI. Clients

must save separate <TOKEN>s for each account, FI, and type of synchronization request.

Usage: All synchronization requests and responses

3.2.5 Transaction Amount <TRNAMT>

Format: Amount

Open Financial Exchange uses <TRNAMT> in any request or response that reports the total

amount of an individual transaction.

Usage: Bank statement download, investment statement download, payments

3.2.6 Memo <MEMO>, <MEMO2>

Format: A-255 for <MEMO>, used in V1 message sets; A-390 for <MEMO2>, used in V2 message sets

A <MEMO> provides additional information about a transaction.

Usage: Bank statement download, investment statement download, payments, transfers

OFX 1.6 Specification 6910/18/99

3.2.7 Date Start and Date End <DTSTART> <DTEND>

Format: Datetime

Clients use these elements in requests to indicate the range of response that is desired. Servers

use these elements in responses to let clients know what the FI was able to produce.

In requests, the following rules apply:

◆ If <DTSTART> is absent, the client is requesting all available history (up to the <DTEND>, if

specified). Otherwise, it indicates the inclusive date and time in history where the client

expects servers to start sending information.

◆ If <DTEND> is absent, the client is requesting all available history (starting from

<DTSTART>, if specified). Otherwise, it indicates the exclusive date and time in history where

the client expects servers to stop sending information.

In responses, the following rules apply:

◆ <DTSTART> is the date and time where the server began looking for information, not

necessarily the date of the earliest returned information. If the response <DTSTART> is later

than the requested <DTSTART>, clients can infer that the user has not signed on frequently

enough to ensure that the client has retrieved all information. If the user has been calling

frequently enough, <DTSTART> in the response will match <DTSTART> in the request.

◆ <DTEND> is the date and time that, if used by the client as the next requested <DTSTART>, it

would pick up exactly where the current response left off. It is the exclusive date and time in

history where the server stopped looking for information, based on the request <DTEND>

rules.

Because the system add date for a transaction is not necessarily the post date for the transaction

(the latter occurring when the account is actually debited or credited), a server should consider

the <DTSTART> and <DTEND> dates in a <(CC)STMTRQ> as a request for any transactions that

were posted or added to the FI system at that time. In addition, the transactions returned should

probably span a greater window of time than that included in the <DTSTART>/<DTEND> dates

since a transaction might be added to the system after a statement download request was made

for that time period. (Clients should be able to filter out the unnecessary transactions.) If a client

is always requesting a download sequentially, through time, is never requesting an end date

using <DTEND> and is always substituting <DTEND> in the response for <DTSTART> in the

next request, it is safe for a server to return only those transactions that had a system add date on

or after <DTSTART> in the request. In all cases, servers are minimally required to use a “system

add datetime” as the basis for deciding which details match the requested date range. For

example, if an FI posts a transaction dated Jan 3 to a user’s account on Jan 5, and a client connects

on Jan 4 and again on Jan 6, the server is required to return that Jan 3-dated transaction when the

client calls on Jan 6.

Usage: Bank statement download, investment statement download

70 3.2 Common Elements

3.2.8 Common Data Types

3.2.8.1 Dates, Times, and Time Zones

There is one format for representing dates, times, and time zones. The complete form is:

YYYYMMDDHHMMSS.XXX [gmt offset:tz name]

3.2.8.2 Date and Datetime

Elements specified as type date or datetime and generally starting with the letters “DT” accept a

fully formatted date-time-timezone string. For example, “19961005132200.124[-5:EST]”

represents October 5, 1996, at 1:22 and 124 milliseconds p.m., in Eastern Standard Time. This is

the same as 6:22 p.m. Greenwich Mean Time (GMT).

Date and datetime also accept values with fields omitted from the right. They assume the

following defaults if a field is missing:

Note that times zones are specified by an offset and optionally, a time zone name. The offset

defines the time zone. Valid offset values are in the range from –12 to +12 for whole number

offsets. Formatting is +12.00 to -12.00 for fractional offsets, plus sign may be omitted.

Take care when specifying an ending date without a time. If the last transaction returned for a

bank statement download was Jan 5 1996 10:46 a.m. and if the <DTEND> was given as just Jan 5,

the transactions on Jan 5 would be resent. If results are available only daily, then just using dates

and not times will work correctly.

Note: Open Financial Exchange does not require servers or clients to use the full

precision specified. However, they are REQUIRED to accept any of these forms

without complaint.

Some services extend the general notion of a date by adding special values, such as “TODAY.”

These special values are called “smart dates.” Specific requests indicate when to use these extra

values, and list the element as having a special data type.

Specified date or datetime Assumed defaults

YYYYMMDD 12:00 AM (the start of the day), GMT

YYYYMMDDHHMMSS GMT

YYYYMMDDHHMMSS.XXX GMT

OFX 1.6 Specification 7110/18/99

3.2.8.3 Time

Elements specified as type time and generally ending with the letters “TM” accept times in the

following format:

HHMMSS.XXX[gmt offset:tz name]

The milliseconds and time zone are still optional, and default to GMT.

3.2.8.4 Time Zone Issues

Several issues arise when a customer and FI are not in the same time zone, or when a customer

moves a computer into new time zones. In addition, it is generally unsafe to assume that

computer users have correctly set their time or time zone.

Although most transactions are not sensitive to the exact time, they often are sensitive to the

date. In some cases, time zone errors lead to actions occurring on a different date than intended

by the customer. For this reason, servers should always use a complete local time plus GMT

offset in any datetime values in a response. If a customer’s request is for 5 p.m. EST, and a server

in Europe responds with 1 a.m. MET the next day, a smart client can choose to warn the customer

about the date shift.

Clients that maintain local state, especially of long-lived server objects, should be careful how

they store datetime values. If a customer initiates a repeating transaction for 5 p.m. EST, then

moves to a new time zone, the customer might have intended that the transaction remain 5 p.m.

in the new local time, requiring a change request to be sent to the server. If, however, the

customer intended it to remain fixed in server time, this would require a change in the local time

stored in the client.

Client software that doesn’t know the current local time zone for the user, or client proxies that

don’t know the current local time zone of their end users, should maintain and display the

datetime value in the time zone indicated by the originator of the value and explicitly marked

with that time zone. As an example, consider <DTPMTDUE> in section 11.5.4.2. If the biller gave

a due date of 23:59pm EST on Dec 29, 1997, this is best displayed as 23:59pm EST rather than

rendered in local time if there is any doubt at all as to the current local time zone of the end user

looking at the due date.

72 3.2 Common Elements

When considering timezone conversions, remember the following differences between the date

and datetime datatypes:

◆ Date = A date without time; this date is explicit. Clients and servers will not convert the value

in any way. Examples include birth date and billing date.

◆ Datetime = A date and time format; clients and servers may convert this date to their local

timezone. Examples include last account update date and bill summary fetch date.

Note: Developers should consider the possibility of a date change due to timezone

conversion. A datetime value in the GMT timezone with a time of 12:00:00 (noon)

would be converted to another time on the same date in every timezone. For example,

199812251200 remains Christmas Day in every timezone.

3.2.9 Amounts, Prices, and Quantities

3.2.9.1 Basic Format

Format: A-32

This section describes the format of numerical values used for amounts, prices, and quantities. In

all cases, a numerical value that does not contain a decimal point has an implied decimal point at

the end of the value. For example, a numerical value of “550” is equivalent to “550.” Trailing and

leading spaces should be stripped. Number format uses a leading sign. Negative number format

uses a minus sign (-). Positive number format uses a plus sign (+). The plus sign is implied for all

amounts and can be omitted.

The following types are defined to have a maximum of 32 characters, including alphabetic

characters, digits and punctuation. However, clients and servers may have specific limits for the

maximum number of digits to the left or right of a decimal point. If a server cannot support a

client request due to the size or precision of a number, the server should return status code 2012.

Amount: Amounts that do not represent whole numbers (for example, 540.32), must include a

decimal point or comma to indicate the start of the fractional amount. Amounts should not

include any punctuation separating thousands, millions, and so forth. The maximum value

accepted depends on the client.

Quantity: Use decimal notation.

Unitprice: Use decimal notation. Unless specifically noted, prices should always be positive.

Rate: Use decimal notation, with the rate specified out of 100%. For example, 5.2 is 5.2%.

Some services define special values, such as INFLATION, which you can use instead of a

designated value. Open Financial Exchange refers to these as “smart types,” and identifies them

in the specification.

OFX 1.6 Specification 7310/18/99

3.2.9.2 Positive and Negative Signs

Most OFX transaction aggregates describe the flow of funds. Amounts in transactions which

clearly describe the flow of funds should normally be positive. For example, investment buys

and sells, bank statement credits and debits should be positive.

Servers should sign amounts from the perspective of the user in cases where the flow of funds

cannot be determined from the transaction aggregate alone. For example, interest amounts can

be either positive or negative, depending on whether the interest is earned or paid. Servers

should also sign amounts in cases of corrections to transaction. For example, a correction to an

Investment Buy Mutual Fund transaction, BUYMF, would contain negatively signed UNITS.

3.2.10 Language

Language identifies the human-readable language used for such things as status messages and e-

mail. Language is specified as a three-letter code based on ISO-639.

3.2.11 Other Basic Data Types

Boolean: Y = yes or true, N = no or false.

currsymbol: A three-letter code that identifies the currency used for a request or response. The

currency codes are based on ISO-4217. For more information about currencies, refer to section

5.2.

URL: String form of a World Wide Web Uniform Resource Location. It should be fully qualified

including protocol, host, and path. A-255.

URL2: URL2 is used in V2 message sets to handle URLs that might contain longer server names,

security tokens and context data. String form of a World Wide Web Uniform Resource Location.

It should be fully qualified including protocol, host, and path. A-1024.

74 3.2 Common Elements

OFX 1.6 Specification 7510/18/99

CHAPTER 4 OFX SECURITY

OFX provides several options for ensuring the security of customer transactions. This chapter

describes the OFX security framework, security goals, types of security, and financial institution

(FI) responsibilities.

4.1 Security Concepts in OFX

4.1.1 Architecture

OFX security applies to the communication paths between a client and the profile server, a client

and the Web server, and, when the OFX server is separate from the Web server, a client and the

OFX server. The diagram below illustrates the initial order in which these communications occur,

assuming that the client already has the URL for the FI profile server.

The bootstrap process for a client is:

◆ From the FI Profile Server, the client gets the URL of the FI Web server, so that it can retrieve a

particular message set.

◆ The client sends an OFX request to the FI Web Server URL, from which it is forwarded to the

OFX Server.

◆ The OFX Server sends back a response to the client via the Web Server.

)LQDQFLDO,QVWLWXWLRQRUUG3DUW\

) LQDQFLDO,QVWLWXWLRQRU7KLUG3DUW\

&/,(1 7

352),/(

6(59(5



,G HQWLILHU

) ,3URILOH

LQFOXGLQJ

:HE6HUYHU85/

:(%

6(59(5

2);



5HTXHVW

2);

6(59(5

2);



5HVSRQVH

76 4.1 Security Concepts in OFX

4.1.2 Security Goals

The main goals of OFX security are:

◆ Privacy: Only the intended recipient can read a message. Encryption is a technique often used

to ensure privacy.

◆ Authentication: The recipient of a message can verify the identity of the sender. In OFX,

passwords allow an FI to authenticate a client, and certificates allow a client to authenticate a

server.

◆ Integrity: A message cannot be altered after it is created A cryptographic hash is often used to

assist integrity verification.

OFX specifies the minimum security required for Internet transactions and provides several

security options, based on existing standards. Through its choice of security techniques and

related options, an FI can achieve privacy, authentication, and integrity with varying degrees of

assurance. For example, there are many kinds of encryption algorithms, most of which can be

strengthened or weakened by changing the key size.

4.1.3 Security Standards

Several standards underlie Type 1 security:

◆ Certificates (X.509 v3) are used to identify and authenticate servers, and to convey their public

keys.

◆ PKCS #1 block type 2 is the encryption format specified by the recipe (See section 4.2.2.4.3).

◆ RSA is the encryption algorithm.

4.1.3.1 Certificates and Certification Authorities

A certificate is a digitally signed document that binds a public key to an identity. It contains a

public key that identifies information such as the name of the person or organization to whom

the key belongs, an expiration date, a unique serial number, and additional descriptive

information.

A certificate is useful for authentication because it is signed by a trusted third-party. This assures

the verifier that the certificate has not been changed since it was signed. The entity which signs

certificates is called a certification authority, or CA. A CA acts somewhat like a notary public: the

reader of a document stamped by a notary public knows that the notary has checked the identity

of the person who originated the document. By digitally signing someone’s identity and public

key, the CA affirms that the two go together.

If the client and server do not share a common CA, the client cannot validate the server’s

certificate. For this reason, OFX specifies a number of trusted CAs that all clients must accept and

all servers must use.

OFX 1.6 Specification 7710/18/99

Certificates are used in Type 1 security, as well as channel-level security through SSL. The format

for these is defined by X.509 version 3. For more information, refer to ITU-T Rec. X.509, ISO/IEC

9594-8.

4.1.3.2 PKCS #1

The acronym, PKCS, stands for “Public Key Cryptography Standards,” a set of standards

developed by a consortium and hosted by RSA. PKCS #1 is the RSA Encryption Standard, the

rules for using RSA public key encryption. For the complete syntax of the PKCS #1 standard,

refer to “Public-Key Cryptography Standards (PKCS)” published by RSA Data Security, Inc. at

http://www.rsa.com/.

4.1.4 FI Responsibilities

OFX is designed with the understanding that there must be a security policy in place at each

supporting financial institution. That policy must clearly delineate how customer data is

secured, and how transactions are managed such that all parties to the transaction are protected

according to accepted and recognized best common practices.

The decision regarding which users may perform a given operation on a given account must be

determined by the financial institution. For example, is the specified user authorized to perform

a transfer from the specified account? The financial institution must also determine whether the

user has exceeded allowed limits on withdrawals, whether the activity on this account is unusual

given past history, and other context-sensitive issues.

Although OFX provides many security options, an FI must support a minimal level of security.

To ensure the proper security configuration, an FI must follow the steps outlined below.

1. Obtain one certificate for the profile server. This certificate must be rooted in one of the

approved Certification Authorities (CAs). Establish appropriate safeguards for this certificate

and its private key.

2. Obtain a certificate, rooted in an acceptable CA, for each OFX server, whether it is operated

by the FI or by a third party.

3. Decide whether to use Type 1 application-level security for any message sets. For each

message set to be secured by Type 1, obtain a certificate.

Type 1 security can be used on any message set, except for the Profile message set.

There are a number of other security issues beyond OFX proper, especially those relating to the

Internet and network engineering. These issues are beyond the scope of this document. FIs are

advised to conduct a complete security review of all servers associated with OFX.

78 4.1 Security Concepts in OFX

4.1.5 Security Levels: Channel vs. Application

With OFX, security can be applied at two different levels in the message exchange process.

◆ Channel level: Generally transparent to a client or server, channel-level security is built into

the communication process, protecting messages between two ends of the “pipe.” To secure

messages during HTTP transport, client and server applications use the Secure Sockets Layer

(SSL) protocol. SSL transparently protects messages exchanged between the client and the

destination Web server. SSL authenticates the destination Web server using the Web server’s

certificate. Additionally, it provides privacy via encryption, and SSL-record integrity, i.e. the

block of data sent in each transmission cannot be altered without detection.

◆ Application level: Transparent to and independent of the transport process, application-level

security protects the user password sent from the client application all the way to the server

application that handles the OFX messages. The server application typically resides beyond

the destination Web server, secured behind an Internet firewall. Application-level security

requires channel-level security.

The following diagram illustrates how channel-level and application-level security relate. The

diagram shows the path of a request from the client to the server when application-level

encryption is used.

Channel-level security is sufficient for most message sets, provided that the network architecture

at the destination is adequately secure; however, application-level password encryption can

allow a more flexible back-end architecture with a high level of security.

&/,(17

:(%

6(59(5

2);

6(59(5

66/(QFU\SWLRQ

2);'DWD

(QFU\SWHG

3DVVZRUG

2);'DWD

(QFU\SWHG

3DVVZRUG

3DVVZRUGVDUHHQFU\SWHGE\WKH

FOLHQWDSSOLFDWLRQDQGE\WKH

66/3URWRFRO

7KH:HEVHUYHUUHPRYHVWKH

66/HQFU\S WLRQDQGIR UZDUGV

WKHHQFU\SWHGSDVVZRUGDQG

SODLQWH[W2);GDWD

OFX 1.6 Specification 7910/18/99

4.2 Security Implementation in OFX

4.2.1 Channel-Level Security

4.2.1.1 Specification in FI Profile

For each message set listed in the FI profile response, the <MSGSETCORE> aggregate describes

the channel-level security required for that message set.

The <TRANSPSEC> element defines whether or not channel-level security is required. It can

have one of the following values:

All currently defined message sets require channel-level security.

4.2.1.2 SSL Protocol

Secure Sockets Layer (SSL) is a cryptographic protocol commonly used for channel-level security

on the Internet. Central to the security of SSL is the server certificate. This certificate assures clients

that the server is who it claims to be. It contains the public key of the server, which the client uses

to encrypt the session keys it generates as part of each connection.

All of this function is available without significant software development on either the client or

server side; however, the client and server must be configured to use appropriate encryption

algorithms (CipherSuites). In addition, clients and servers must share a trusted root certificate, or

the client will not be able to validate the server’s certificate.

Note: Although SSL supports client-side certificates to allow a server to authenticate a

client, OFX does not require them at this time. To identify and authenticate a customer,

servers should use the information provided in the signon request <SONRQ>.

Setting the <TRANSPSEC> element to Y means that the client must use SSL v3 or higher.

Tag Description

N Do not use any channel-level security

Y Use channel-level security

80 4.2 Security Implementation in OFX

4.2.1.3 Trusted Certificate Authorities

Both channel-level and application-level security rely on clients and servers having at least one

trusted certification authority (CA) in common. To ensure that clients can test the validity of a

certificate, servers must have their certificates signed by an approved OFX CA. Clients are

assumed to have access to this trusted CA.

4.2.1.4 CipherSuites

The following SSL CipherSuites are approved for use with OFX:

◆ SSL_RSA_WITH_RC4_128_SHA

◆ SSL_RSA_WITH_IDEA_CBC_SHA

◆ SSL_RSA_WITH_DES_CBC_SHA

◆ SSL_RSA_WITH_3DES_EDE_CBC_SHA

◆ SSL_DH_DSS_WITH_DES_CBC_SHA

◆ SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA

◆ SSL_DH_RSA_WITH_DES_CBC_SHA

◆ SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA

◆ SSL_DHE_DSS_WITH_DES_CBC_SHA

◆ SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA

◆ SSL_DHE_RSA_WITH_DES_CBC_SHA

◆ SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA

Other CipherSuites are not approved.

4.2.1.5 Key Size

Signing keys must be either RSA with a minimum 1024-bit modulus, or DSS with a 1024-bit

modulus.

Server RSA keys and Diffie-Hellman keys must both have a minimum 1024-bit modulus. The

Diffie-Hellman base must be primitive.

OFX 1.6 Specification 8110/18/99

4.2.2 Application-Level Security

4.2.2.1 Specification in FI Profile

For each message set listed in the FI profile response, the <MSGSETCORE> aggregate describes

the security required for that message set.

The <OFXSEC> element defines the type of application-level security required for the message

set. <OFXSEC> can have one of the following values, which also are used in the SECURITY

element of the OFX headers:

Application-level security requires channel-level security.

4.2.2.2 Type 1 Protocol Overview

The goal of the Type 1 protocol is to protect the user password all the way to the destination OFX

server. In the absence of client certificates, this password is the primary vehicle for client

authentication and is therefore worthy of special consideration.

Type 1 requires channel-level security, i.e. SSL. Though the password is well protected by SSL

alone in the client to Web server connection, the server-side network architecture may render the

password less secure while it is in transit between the Web and OFX servers. With Type 1, the

user password is not decrypted until the request reaches the OFX server.

Type 1 applies only to the request part of a message; the server response is unaffected.

A simple approach would be to deliver the server’s Type 1 certificate in the profile and use it to

encrypt the password, but that would permit a replay attack. An attacker could capture a

transaction, including encrypted password, and replay it to the server. It wouldn’t matter that

the password remained unknown.

To prevent the replay attack, the server introduces some random data to the process, data which is

unpredictably different for each transmission. The client asks for the random data with a

challenge request. The server sends it, along with its Type 1 certificate, in the challenge response.

The client then uses that random data in the encryption process, thereby assuring the server that

the client response is associated with this and only this interaction.

Tag Description

NONE Do not use any application-level security

TYPE1 Use Type 1 application-level security

82 4.2 Security Implementation in OFX

The following diagram illustrates:

4.2.2.3 Type 1 Protocol Notation

In this section, the expression, C = E

(M), means that plain text M is encrypted either

symmetrically or asymmetrically with key A into ciphertext C. The expression, M = D

(C)

signifies the inverse operation (decryption), in which ciphertext C is decrypted into plain text M

using key A. If C was encrypted asymmetrically, then A in the latter case is understood to be the

private component of the key. The expression, A || B, indicates that B is concatenated to A.

4.2.2.4 Type 1 Protocol Implementation

Type 1 application-level security provides additional password secrecy. These are the steps for

conducting a Type 1 transaction (unless otherwise noted, the term “Server” in this section refers

to the Financial Institution Server):

1. Client obtains the Server’s profile from the Profile Server (see Chapter 7, "

FI Profile")

2. Client establishes an SSL connection with the Server (see section 4.2.1

)

3. Client sends <CHALLENGERQ> to Server (see section 4.2.2.4.1

)

4. Server sends <CHALLENGERS> which contains a nonce and the Server’s Type 1 certificate

(see section 4.2.2.4.2

)

5. Client builds a transaction request and sends it to the Server (see section 4.2.2.4.3

)

6. Server parses the request, verifying the user password, and either rejects or processes the

transaction (see section 4.2.2.4.4

)

&/,(17

&KDOOHQ

HUH

XHVW

:(%

6(59(5

2);

6(59(5

&KDOOHQJHUHVSRQVH

ZUDQGRPGDWD

2);UHTXHVWZ

HQFU\SWHG S DVVZRUG

2);UHVSRQVH

OFX 1.6 Specification 8310/18/99

The following table lists data elements used in the Type 1 protocol:

Field Type Description

BT octet, length 1 Block Type byte.

BT = 0x02

CT1 octet string, length 128 Ciphertext: the PKCS #1 RSA encryption of EB with KS.

CT1 = E

(EB)

CT2 printable ASCII, length 171 Encoded Ciphertext: the RADIX-64 encoding of CT1

(see RFC 1113, §4.3.2.4 and §4.3.2.5).

CT2 = RADIX64(CT1)

D octet string, length 68 Data: the user data to be encrypted.

D = NC || P || T

EB octet string, length 128 Encryption Block: the formatted plain text block, ready

for encryption.

EB = 0x00 || BT || PS || 0x00 || D

KS RSA key, modulus length 1,024 bits Server’s Type 1 RSA key

NC octet string, length 16 Client Nonce: string of random octets generated by the

Client

NS octet string, length 16 Server Nonce: string of random octets generated by the

Server

P printable ASCII, null-padded, length

Password: shared by the Client and Financial

Institution, null-padded on the right

PS octet string, length 57 Padding String: each octet is pseudo-random and non-

zero

T octet string, length 20 Authentication Token.

T = SHA1(NS || P || NC)

84 4.2 Security Implementation in OFX

struct {

unsigned char nc[16];

unsigned char p[32];

unsigned char t[20];

} D;

struct {

unsigned char null1 = 0x00;

unsigned char bt = 0x02;

unsigned char ps[57];

unsigned char null2 = 0x00;

struct D d;

} EB;

4.2.2.4.1 Challenge request

Client sends a <CHALLENGERQ> to the Server.

4.2.2.4.2 Challenge response

Server sends a <CHALLENGERS> to the client. This response contains the Server’s Type 1

certificate and NS.

4.2.2.4.3 Building the OFX Request

1. Client generates 16 random octets and places them in NC (see RFC 1750 for

recommendations on entropy generation)

2. Client obtains the User’s password (P)

3. Client computes T = SHA1(NS || P || NC)

4. Client generates 57 pseudo-random, non-zero octets and places them in PS (NC

may be used

to seed the pseudo-random number generator)

5. Client sets D = NC || P || T

6. Client sets EB = 0x00 || BT || PS || 0x00 || D

7. Client RSA-encrypts EB using the Server’s Type 1 public key (obtained from the Server’s

Type 1 certificate): CT1 = E

(EB) (see PKCS #1, §§8.2-8.4)

8. Client encodes the ciphertext for transport: CT2 = RADIX64(CT1). See RFC 1113, §4.3.2.4 and

§4.3.2.5. This is a standard encoding method supported by RSA’s Bsafe library and others.

9. Client constructs the body of its OFX request

10. Client copies CT2 to the <USERPASS> field of the OFX <SONRQ>

11. Client sends the complete OFX request to the Server

In <PINCHRQ>, the steps are identical, except that in step 2, P is set to <NEWUSERPASS> and

in step 10, CT2 is copied to the <NEWUSERPASS> field of the <PINCHRQ>.

OFX 1.6 Specification 8510/18/99

The diagram below illustrates the creation of CT2.

E\WHV

E\WHV

E\WHV

E\WHV

6+$

E\WHV

E\WH

[

E\WH

[

E\WH

E\WHV

&7

E\WHV

( 5

&7

E\WHV

6+$

(

5

6+$KDVK

FRQFDWHQDWLRQ

56$HQFU\SWLRQZLWK6HUYHUV

SXEOLFNH\

5$',;HQFRGLQJ

/HJHQG

E\WHV

86 4.2 Security Implementation in OFX

4.2.2.4.4 Parsing the OFX Request

1. Server reads the OFX SECURITY header in the request file to ascertain whether Type 1

processing should be used on this message. If Type 1 is not used, skip to step 6

2. Server extracts CT2 from the <USERPASS> field of the OFX <SONRQ> and removes the

encoding to obtain CT1 (see RFC 1113, §4.3.2.4 and §4.3.2.5)

3. Server decrypts CT1 to obtain EB: EB = D

(CT1) (see PKCS #1, §9)

4. Server extracts D from EB, then extracts NC, P, and T from D

5. Server looks up the Client’s password in its database, and computes SHA1(NS || P || NC).

If the result does not match T, Server terminates the session and reports the error to the client

6. Server processes the request and returns confirmation to the Client

In <PINCHRQ>, the steps are identical except that in step 2, CT2 is obtained from the

<NEWUSERPASS> field of the <PINCHRQ> and in step 5

, the server does not look up the

extracted new password in a database.

OFX 1.6 Specification 8710/18/99

CHAPTER 5 INTERNATIONAL SUPPORT

5.1 Language and Encoding

Most of the content in OFX is language-neutral. However, some error messages, balance

descriptions, and similar elements contain text meant to appear to the financial institution

customers. There are also cases, such as e-mail records, where customers need to send text in

other languages. To support worldwide languages, OFX must identify the basic text encoding,

character set, and language.

The OFX headers specify the encoding and character set, as described in Chapter 2, "

Structure."

Current encoding values are USASCII and UTF-8. For USASCII, character set values are code

pages. UTF-8 ignores the character set per se although it still requires the syntax. UTF-8 is a form

of UNICODE defined in International ISO/IEC 10646-1, amendment 2. Servers must respond

with the encoding and character set requested by the client.

CHARSET defines the character set used for character data. The values for CHARSET may be

ISO-8859-1 (Latin-1), 1252 (Windows Latin-1), or NONE. Any value specified here is likely to be

ignored by an OFX client or server.

Clients identify the language in the signon request. OFX specifies languages by three-letter codes

as defined in ISO-639. Servers report their supported languages in the profile (see Chapter 7, "

Profile"). If a server cannot support the language requested by the client, it must return an error

and not process the rest of the transactions.

5.2 Currency <CURDEF> <CURRENCY> <ORIGCURRENCY>

In each transaction involving amounts, responses include a default currency identification,

<CURDEF>. The values are based on the ISO-4217 three-letter currency identifiers.

Within each transaction, specific parts of the response might need to report a different currency.

Where appropriate, aggregates include an optional <CURRENCY> aggregate. The scope of a

<CURRENCY> aggregate is everything within the same aggregate that the <CURRENCY>

aggregate appears in, including nested aggregates, unless overridden by a nested

<CURRENCY> aggregate. For example, specifying a <CURRENCY> aggregate in an investment

statement detail means that the unit price, transaction total, commission, and all other amounts

are in terms of the given currency, not the default currency.

Note that there is no way for two or more individual elements that represent amounts—and are

directly part of the same aggregate—to have different currencies. For example, there is no way in

a statement download to have a different currency for the <LEDGERBAL> and the

<AVAILBAL>, because they are both directly members of <STMTRS>. In most cases, you can use

88 5.2 Currency <CURDEF> <CURRENCY> <ORIGCURRENCY>

the optional <BAL> aggregates to overcome this limitation, since <BAL> aggregates accept

individual <CURRENCY> aggregates.

The default currency for a request is the currency of the source account. For example, the

currency for <BANKACCTFROM>.

The <CURRATE> should be the one in effect throughout the scope of the <CURRENCY>

aggregate. It is not necessarily the current rate. Note that the <CURRATE> needs to take into

account the choice of the FI for formatting of amounts (that is, where the decimal is) in both

default and overriding currency, so that a client can do math. This can mean that the rate is

adjusted by orders of magnitude (up or down) from what is commonly reported in newspapers.

In some cases, OFX defines transaction responses so that amounts have been converted to the

home currency. However, OFX allows FIs to optionally report the original amount and the

original (foreign) currency. In these cases, transactions include a specific aggregate for the

original amount, and then an <ORIGCURRENCY> aggregate to report the details of the foreign

currency.

Again, <CURRENCY> means that OFX has not converted amounts. Whereas,

<ORIGCURRENCY> means that OFX has already converted amounts.

Tag Description

Currency aggregate

Ratio of <CURDEF> currency to <CURSYM> currency, in decimal form, rate

ISO-4217 3-letter currency identifier, currsymbol

</CURRENCY>

</ORIGCURRENCY>

OFX 1.6 Specification 8910/18/99

5.3 Country-Specific Element Values

Some of the elements in OFX have values that are country-specific. For example,

<USPRODUCTTYPE> is useful only within the United States. OFX will extend in each country

as needed to provide elements that accept values useful to that country. Clients in other countries

that do not know about these elements must simply skip them.

In some cases, an element value represents a fundamental way of identifying something, yet

there does not exist a world-wide standard for such identification. Examples include bank

accounts and securities. In these cases, OFX must define a single, extensible approach for

identification. For example, CUSIPs are used within the U.S., but not in other countries.

However, CUSIPs are fundamental to relating investment securities, holdings, and transactions.

Thus, a security ID consists of a two-part aggregate: one to identify the naming scheme, and one

to provide a value. OFX will define valid naming schemes as necessary for each country.

90 5.3 Country-Specific Element Values

OFX 1.6 Specification 9110/18/99

CHAPTER 6 DATA SYNCHRONIZATION

6.1 Overview

Currently, some systems provide only limited support for error recovery and no support for

backup files or multiple clients. This chapter defines OFX’s powerful means of data

synchronization between clients and servers.

OFX data synchronization addresses the following problems:

◆ Error recovery

◆ Use of multiple data files, including multiple client applications

◆ Restoring from an outdated backup file

This chapter first provides a brief introduction to synchronization problems and then presents

the strategy used in OFX to ensure data integrity. Additional details about synchronization

requests and responses may be found in the relevant sections of this document. The final section

in this chapter discusses alternatives to full synchronization and summarizes the options for

each.

6.2 Background

When a connection between the client and the server does not successfully complete, there are

two main areas of concern:

◆ Unconfirmed requests

If a client does not receive a response to work it initiates, it has no way of knowing whether

the server processed the request. It also does not have any server-supplied information about

the request, such as a server ID number.

◆ Unsolicited data

Some message sets allow a server to send data to the client without first receiving a request.

OFX assumes that the first client to connect after the unsolicited data is available receives it. If

the connection fails, this information could be forever lost to the client. Examples of

unsolicited data include updates to the status of a bill payment and e-mail messages.

Unsolicited data presents problems beyond error recovery. Because the first client that connects

to a server is the only one to receive unsolicited data, this situation precludes use of multiple

clients without a data synchronization method. For example, if a user has a computer at work

and one at home, and wants to perform online banking from both computers, a bank server

could send unsolicited data to one but not the other.

92 6.3 Data Synchronization Approach

An even greater problem occurs when a user resorts to an outdated backup copy of the client

data file. This backup file may be missing recent unsolicited data with no way to retrieve it from

the server again.

6.3 Data Synchronization Approach

A simple solution is to make sure that clients can always obtain information from the server for a

reasonable length of time after it is initially sent. Clients can request recent responses—whether

due to client-initiated work or other status changes on the server—by supplying the previous

endpoint in the response history. Servers should always supply a new endpoint whenever they

supply responses. These endpoints are described by the <TOKEN> element.

To ensure a consistent state after a failure (for example, dropped client connections or a client

crash before updating its database), the client must store all data returned in a sync response

before updating the saved token for that account and object type. After a failure, the next sync

attempt using the old token might download information already reflected in the client database.

But, re-integration of that data is much preferred over losing all changes between the old and

new token values.

If a user switches to an outdated backup file, then the most recent endpoint known to the client

will be older than the most recent endpoint known to the server.

If multiple clients are in use, each will send requests based on its own current endpoint, so that

both clients will obtain complete information from the server. This is one reason why OFX

responses carry enough information from the request to enable them to be processed

independent from the requests. The diagram below shows the interaction between clients and

servers.

OFX 1.6 Specification 9310/18/99

OFX relieves the server from maintaining any special error-recovery state information. However,

OFX requires the server to maintain a history of individual responses and a <TOKEN> to

identify a position in the history. This token is commonly a time stamp, but it need not be.

Because of the freedom a server has in choosing values for its <TOKEN>s, a client must not

assume any sequential relationship between <TOKEN>s based on the <TOKEN> values.

Note: OFX does not require servers to store responses based on individual

connections. Also, not all requests are subject to synchronization. For example, OFX

does not require servers to store statement-download responses separately for data

synchronization.

6.4 Data Synchronization Specifics

OFX performs synchronization separately for each type of response. In addition, a

synchronization request might include further identifying information, such as a specific account

number. This specification defines the additional information for each synchronization request.

Each OFX service identifies the objects that are subject to data synchronization. For example, a

bank-statement download is a read-only operation from the server. A client can request it again;

consequently, there is no data synchronization for this type of response.

'$7$6(59(5



)LQDQFLDO,QVWLWXWLRQ



7UDQVDFWLRQ

7UDQVDFWLRQ

7UDQVDFWLRQ

7UDQVDFWLRQ

7UDQVDFWLRQ

7UDQVDFWLRQ

7UDQVDFWLRQ

7UDQVDFWLRQ

7UDQVDFWLRQ

&/,(17



&XVWRPHU



7UDQVDFWLRQ

7UDQVDFWLRQ

7UDQVDFWLRQ

7UDQVDFWLRQ

7UDQVDFWLRQ

7UDQVDFWLRQ

7UDQVDFWLRQ

&/,(17



&XVWRPHU



7UDQVDFWLRQ

7UDQVDFWLRQ

7UDQVDFWLRQ

7UDQVDFWLRQ

&OLHQWVHQGV

WRNHQ

6HUYHUUHV

RQGV

LWKWUDQVDFWLRQV

&OLHQWVHQGV

WRNHQ

6HUYHUUHV

RQGV

LWKWUDQVDFWLRQV

94 6.4 Data Synchronization Specifics

6.4.1 Tokens

The basis for synchronization is a token as defined by the <TOKEN> element. The server can

create a token in any way it wishes. The client simply holds the token for possible use in a future

synchronization request.

The server can derive a token from one of the following:

◆ Time stamp

◆ Sequential number

◆ Unique nonsequential number

◆ Other convenient values for a server

OFX reserves the following tokens:

◆ <TOKEN>0 (zero) requests all available history for the referenced account (if specified) and

object type. Servers should send all relevant transactions that are accessible, allowing a new

client to know about work done by other clients. If a user’s account has never been used with

OFX, the server returns no history.

◆ Servers should return <TOKEN>–1 (negative one) in the event they must respond with an

error. Since there is no <xxxTRNRS> wrapper inside the <xxxSYNCRS> wrapper, the

<SYNCERROR> element was added in version 2 to allow the server to return the value that

would normally be in the <CODE> field of the <STATUS> aggregate. For more information,

see section 6.4.4

In all other cases, the server can use different types of tokens for different types of responses, if

suitable for the server.

Clients must send either a <REFRESH>Y request (if supported by the server) or <TOKEN>0 in

their initial synchronization request for each account (if necessary) and object type. As described

in section 6.6

, a server’s response to either request should bring the client up-to-date. The

<REFRESH>Y response would not detail how or when an object reached its current state. But,

the <TOKEN>0 response might not list every relevant object (for example, some early history

that the server has already purged, which might include a payment that was scheduled far in the

past, but not yet due.) Should the client require full history information initially, OFX

recommends a <REFRESH>Y request together with a <TOKEN>0 request.

Tokens can contain up to 10 characters in V1 message sets, and 36 in V2 message sets; see

Chapter 3, "

Common Aggregates, Elements, and Data Types." Tokens must be unique only with

respect to the type of synchronization request and the additional information in that request. For

example, a bill payment synchronization request takes an account number; therefore, a token

needs to be unique only within payments for the account. In sync requests which do not include

an account number, token values are scoped to the current user. For example, a token in a payee

synchronization request needs to be unique only within payees for the signed on user.

OFX 1.6 Specification 9510/18/99

The server can use different types of tokens for different types of responses, if suitable for the

server.

Servers will not have infinite history available, so synchronization responses can optionally

include a <LOSTSYNC>Y (yes) if the old token in the synchronization request was older than the

earliest available history. This element allows clients to alert users that some responses have been

lost.

Note: Tokens are unrelated to <TRNUID>s, <SRVRTID>s, and <FITID>s, each of

which serves a specific purpose and has its own scope and lifetime.

A <SRVRTID> is not appropriate as a <TOKEN> for bill payment. A single payment has a single

<SRVRTID>, but it can undergo several state changes over its life and thus have several entries

in the token history.

6.4.2 The Synchronization Process

There are three different ways a client and a server can conduct their requests and responses:

◆ Explicit synchronization—A client can request synchronization without sending any other

OFX requests. The client sends a synchronization request, including the current token for that

type of request. The response includes responses more recent than the given token, along with

the current token.

◆ Synchronization with new requests—A client can request synchronization as part of any new

request. The client gives the latest token it has. The response includes responses to the new

requests plus any others that became available since the time of the token in the request, along

with the current token. An aggregate contains the requests so that the server can process the

new requests and update the token as a single action.

◆ New requests without synchronization—A client can make new requests without providing a

token. In this case, it expects only responses to the new requests. A subsequent request for

synchronization will cause the server to send this response again, because the client did not

receive the current token.

SYNC responses should return a new <TOKEN> only if new activity was generated for a set of

transactions (e.g. payee, payment, intrabank transfers, payment email, etc.). Alternatively, if a

server always returns a new <TOKEN> even if no new activity was generated, the server should

remember that the old and new <TOKEN> values are both up-to-date with respect to

<REJECTIFMISSING>Y

Each request and response that requires data synchronization will define a synchronization

aggregate. The aggregate tells the server which kind of data it should synchronize. By

convention, these aggregates always have SYNC as part of their names, for example,

<PMTSYNCRQ>. These aggregates can be used on their own to perform explicit

synchronization, or as wrappers around one or more new transactions. For example,

<PMTSYNCRQ> aggregates request synchronization and may include new work.

96 6.4 Data Synchronization Specifics

Some clients can choose to perform an explicit synchronization before sending any new requests.

This practice allows clients to be up-to-date before sending any new requests. Other clients can

simply send new requests as part of the synchronization request.

If a client synchronizes in one file, then sends new work inside a synchronization request in a

second file, there is a small chance that additional responses became available between the two

connections. There is an even smaller chance that these would be conflicting requests, such as

modifications to the same object. However, some clients and some requests might require

absolute control, so that the user can be certain that they are changing known data. To support

this, synchronization requests can optionally specify <REJECTIFMISSING> element. The

element tells a server that it should reject all enclosed requests if the supplied <TOKEN> is out of

date before considering the new requests. That is, if any new responses became available,

whether related to the incoming requests or not (but in scope of the synchronization request), the

server should immediately reject the requests. It should still return the new responses. A client

can then try again until it finds a stable window to submit the work. See section 6.5

for more

information about conflict detection and resolution.

Note: If <REJECTIFMISSING>Y causes enclosed requests to be rejected, this rejection

can be done in one of two ways:

◆ Embedded requests are completely ignored – they are not included in the response.

◆ Embedded requests are returned with a 2000 (or 6502 for recent servers) error. This is the

preferred approach.

The password change request and response present a special problem. See section 2.5.2

for

further information.

OFX 1.6 Specification 9710/18/99

6.4.3 Synchronizable Objects

OFX allows synchronization of email (in all message sets), service activations, changes to user

information, stop checks, banking notifications, transfers (both types), recurring transfers (both

types), wire transfers, payees, payments, and recurring payments. OFX includes the following

synchronization request/response pairs.

Section Request Response

8.6.4 <ACCTSYNCRQ> <ACCTSYNCRS>

8.7

9.2.4

11.12.1

11.12.2

11.12.3

11.12.4

11.12.5

11.12.6

11.12.7

12.8.2

12.9.4 <PAYEESYNCRQ> <PAYEESYNCRS>

12.10.1

12.10.2

13.10.2 <INVMAILSYNCRQ> <INVMAILSYNCRS>

14.6

98 6.5 Conflict Detection and Resolution

6.4.4 <SYNCERROR> Status Codes

The <SYNCERROR> element within synchronization aggregates, allows the server to return the

value that would normally be in the <CODE> field of the <STATUS> aggregate. Values for

<SYNCERROR> can include, but are not limited to, the following.

<SYNCERROR> codes 2002, 2003, 2004, and 2005 must not be used with the <MAILSYNCRS>,

messages since those message sets do not include fields to identify a specific account.

When <SYNCERROR> is any value other than 0, any requests embedded within the

synchronization aggregate should return a transaction response <xxxTRNRS> aggregate

containing the same error code except for using <STATUS><CODE>6502 when

<SYNCERROR>6501 appears in the surrounding wrapper. Such requests should not result in a

response <xxxRS> aggregate.

6.5 Conflict Detection and Resolution

Conflicts arise whenever two or more clients or servers modify the same data. This can happen

to any object that has a <SRVRTID> that supports change or delete requests. For example, two

spouses might independently modify the same recurring bill payment model. From a server

perspective, there is usually no way to distinguish between the same user making two intended

changes and two separate users making perhaps unintended changes. Therefore, OFX provides

enough tools to allow clients to detect and resolve conflicts.

A careful client always synchronizes before sending any new requests. If any responses come

back that could affect a user’s pending requests, the client can ask the user whether it should still

Code Meaning

0 Success (INFO)

2000 General error (ERROR)

The server may return <SYNCERROR>2000 when the history query itself failed. For

example, this error would be appropriate when the server is unable to reach its data store.

2002 General account error (ERROR)

2003 Account not found (ERROR)

2004 Account closed (ERROR)

2005 Account not authorized (ERROR)

6500 <REJECTIFMISSING>Y invalid without <TOKEN>(ERROR).

6501 Embedded transactions in request failed to process: Out of date (WARNING)

15500 Signon invalid (ERROR)

OFX 1.6 Specification 9910/18/99

send those pending requests. Because there is a small chance for additional server actions to

occur between the initial synchronization request and sending the user’s pending requests,

extremely careful clients can use the <REJECTIFMISSING> element. Clients can iterate sending

pending requests inside a synchronization request with <REJECTIFMISSING> and testing the

responses to see if they conflict with pending requests. A client can continue to do this until a

window of time exists wherein the client is the only agent trying to modify the server. In reality,

this will almost always succeed on the first try.

6.6 Synchronization Options

There are some situations and some types of clients for which it is preferable that the client ask

the server to send—by way of a refresh—everything it knows, rather than just a set of changes by

way of a synch response. For example, a client that has not connected often enough may have

lost synchronization, a user may create a new data file, or the user might be using a completely

stateless client, such as a Web browser.

Note: OFX does not require a client to refresh just because it has lost synchronization.

Clients will mainly want to refresh lists of long-lived objects on the server; generally objects with

a <SRVRTID>. A brand new client, or a client that lost synchronization, might want to learn

about in-progress payments by doing a synchronization refresh of the payment requests. It

would almost certainly want to do a synchronization refresh of the recurring payment models,

because those often live for months or years.

A client may request a refresh by using <REFRESH>Y instead of the <TOKEN> element. Servers

must send responses that emulate a client creating or adding each of the objects governed by the

particular synchronization request.

When responding to a <REFRESH>Y sync request, servers must send <TRNUID>0 in each

contained transaction wrapper, the standard value for server-generated responses (except

responses for embedded transactions).

There is no need to recreate a stream of responses that emulate the entire history of the object. An

add response that reflects the current state is sufficient. For example, if you create a model and

then modify it several times, even if this history would have been available for a regular

synchronization, servers should only send a single add that reflects the current state.

Due to the large volume of data which might be included in the response, clients should not

perform <MAILSYNCRQ> (or, one of the service-specific equivalents such as

<BANKMAILSYNCRQ>) with <REFRESH>Y.

A client that wants only the current token, without refresh or synchronization, makes requests

with <TOKENONLY>Y.

100 6.6 Synchronization Options

In all cases, servers should send the current ending <TOKEN> for the synchronization request in

refresh responses. This allows a client to perform regular synchronization requests in the future.

The following table summarizes the options in a client synchronization request:

Note: Compliant clients should not send synchronization requests matching those

listed below. Nonetheless, servers should handle such requests and respond as

described.

◆ <TOKENONLY>N has the same meaning as <TOKENONLY>Y and should be treated

identically.

◆ <REFRESH>N has the same meaning as <REFRESH>Y and should be treated identically.

◆ If a client embeds transaction requests in a <REFRESH> or <TOKENONLY> sync request,

the server should respond in such a way that the <REFRESH> data or returned <TOKEN>

reflects a specific state, after the transactions have processed. Since servers are not required

to reduce the data about any particular object to a single addition response, embedded

transactions may be processed before or after the <REFRESH> data is retrieved. As with all

synchronization responses, the returned <TOKEN> must reflect the actions of all

embedded transactions.

◆ <REJECTIFMISSING>Y is illegal unless accompanied by <TOKEN> or <TOKEN2>

(depending on the message set version). If received in the same wrapper as

<TOKENONLY> or <REFRESH>, the server should fail that synchronization request (as

described in section 6.6.1)

. In V2 message sets and <PRESDLVMSGSRSV1>,

<SYNCERROR>6500 is appropriate for this case.

Tag Version Description

Client synchronization

option; <TOKEN>,

<TOKEN2>,

<TOKENONLY>, or

<TOKEN>

V1 only Previous value of <TOKEN> received for this type of

synchronization request from server; 0 for first-time requests;

token

V2 only Previous value of <TOKEN2> received for this type of

synchronization request from server; 0 for first-time requests;

token2

Request for just the current <TOKEN> without the history,

Boolean

Request for refresh of current state, Boolean

If Y, do not process requests if client <TOKEN> is out of date,

Boolean

OFX 1.6 Specification 10110/18/99

6.6.1 Synchronization Errors

When a client sends an unrecognized or “bad” token, the server response should be one of the

following. (Note that <LOSTSYNC> is an optional element):

◆ Return <TOKEN>-1, <LOSTSYNC>N, with no history

◆ Return <TOKEN>X (the current token), <LOSTSYNC>N, with no history

◆ Return <TOKEN>X (the current token), <LOSTSYNC>N, with full history (i.e. treat as if it

were a <TOKEN>0)

If the synchronization request included a bad account number or BANKID, or signon failed, or

an account was closed, etc. the response should include <TOKEN>–1, optionally

<LOSTSYNC>N, and no history.

In all cases, the response should include an appropriate <SYNCERROR> if available within the

context. That is, the optional <SYNCERROR> element should be used in all error cases that occur

in the version 2 or Bill Presentment message sets.

6.7 Typical Server Architecture for Synchronization

This section describes how an FI can approach supporting synchronization based on the

assumption that modifications to an existing financial server will be kept to a minimum.

The simplest approach is to create a history database separate from the existing server. This

history could consist of the actual OFX transaction responses (<xxxTRNRS> aggregates) that are

available to a synchronization request, or simply the information required to re-create the

responses upon request from the client. The history database could index records by token,

response type, and any other identifying information for that type, such as account number.

Clearly, this database must include all <TRNUID>s for all transactions it contains. OFX

recommends that <TRNUID>s be stored for as long as possible so that they may be used to

detect duplicate client requests even after the original requests have been purged from the synch

database.

The diagram below shows a high-level model of the OFX architecture for a financial institution.

Notice that the diagram shows the presence of a history journal.

102 6.7 Typical Server Architecture for Synchronization

The server adds responses to the history journal for any action that takes place on the existing

server. This is true whether the OFX requests initiate the action or, in the case of recurring

payments, it happens automatically on the server. Once added to the history journal, the server

can forget them.

The areas of the OFX server that process synchronization requests need only search this history

database for matching responses that are more recent than the incoming token.

For a refresh request, an OFX server would access the actual bank server to obtain the current

state rather than recent history.

Periodically the bank server would purge the history server of older entries.





FFRXQW

5HFRUGV

,17(51(7

2);

6HUYHU

7HOOHU

6HUYLFHV

%DQN6HUYHU

+LVWRU\-RXUQDO

&OLHQW

),1$1&,$/,167,787,21

(19,5210(17

7UDQVDFWLRQ

0DQDJHU

6\QFKURQL]DWLRQ

5HTXHVW5HVSRQVH

OFX 1.6 Specification 10310/18/99

Only requests that are subject to synchronization need to have entries in the history database.

Statement downloads do not involve synchronization; therefore, the FI server should not add

these responses to the history database. Since statement downloads are usually the largest in

space and the most frequent, eliminating these saves much of the space a response history might

otherwise require.

More sophisticated implementations can save even more space. The history database could save

responses in a coded binary form that is more compact than the full OFX response format. Some

FIs might have much or all of the necessary data already in their servers; consequently, they

would not require new data. An FI could regenerate synchronization responses rather than recall

them from a database.

6.8 Typical Client Processing of Synchronization Results

The diagram below shows a general flowchart of what an OFX client would do with the results

of a synchronization request. Most requests and responses subject to data synchronization

contain both <TRNUID> and <SRVRTID>.

7KHUHV

RQVHLVDPRGLILFDWLRQRUFKDQ

HLQVWDWXV

'RHVWKH65957,'!LQ

WKLVUHVSRQVHPDWFKRQH

DOUHDG\UHFRUGHGE\WKH

FOLHQW"

&OLHQWDSSOLHVDOOXSGDWHG

LQIRUPDWLRQWRLWVFRS\RI

WKHPDWFKLQJWUDQVDFWLRQ

7KHFOLHQWVKRXOGUHFRUGWKH

DVVRFLDWHG65957,'!LI

UHVSRQVHVWDWXV 68&&(66

7KLVLVDUHVSRQVHWRD

UHTXHVWLQLWLDWHGE\WKLV

FOLHQW

7KHUHV

RQVHLVDQHZWUDQVDFWLRQFUHDWHGE

DQRWKHUFOLHQW

:DVWKH7518,'!

UHWXUQHGLQWKHUHVSRQVH

FUHDWHGE\WKLVFOLHQW"

<HV

&OLHQWDGGVWKHWUDQVDFWLRQ

WRLWVORFDOOLVWRI

WUDQVDFWLRQV

7KHUHV

RQVHLVWRDQDGGUH

XHVWIURPWKLVFOLHQW

104 6.9 Simultaneous Connections

6.9 Simultaneous Connections

It is increasingly common for a server to get simultaneous or overlapping requests from the same

user from two different front ends. OFX requires a server to process each set of requests sent in a

file as an atomic action. Servers can deal with the problems that arise with simultaneous use in

two ways:

◆ Allow simultaneous connections, ensure each is processed atomically, and use the data

synchronization mechanism to bring the two clients up to date. This is the preferred method.

◆ Lock out all but one user at a time, returning the error code 15501 for multiple users.

6.10 Synchronization Alternatives

Although it is RECOMMENDED that OFX servers implement full synchronization as described

in this chapter, an alternate approach, “lite synchronization,” could be easier for some servers to

support. This approach focuses only on error recovery and does not provide any support for

multiple clients, multiple data files, or use of backup files. The approach is to preserve the

message sets while simplifying the implementation.

In addition, some clients might prefer to use file-based error recovery with all servers, even if the

client and some servers support full synchronization. This section first describes file-based error

recovery and lite synchronization, and then explains the rules that clients and servers use to

decide how to communicate.

Lite synchronizing servers may support both file-based error recovery and <REFRESH>Y. This

type of server is called a Refresh-capable Lite Synchronizing Server.

For information on how these types of synchronization are profiled, see section 7.2.1

OFX 1.6 Specification 10510/18/99

6.10.1 File-Based Error Recovery

Because only full synchronization supports error recovery, an alternative is needed for lite

synchronization. Servers using lite synchronization keep a copy of the entire response file they

last sent. This is the basis for what is often called “file-based error recovery.” Clients requesting

that servers prepare for error recovery generate a globally unique ID for each file they send. Two

OFX headers are associated with error recovery:

◆ OLDFILEUID—UID of the last request and response that was successfully received and

processed by the client

◆ NEWFILEUID—UID of the current file

The format of these is the same as used with <TRNUID> as documented in section 2.4.6

Servers use the following rules:

◆ If NEWFILEUID is set to NONE, the client is not requesting file-based error recovery for this

session. The server does not need to save the response file. If NEWFILEUID is set to NONE

and OLDFILEUID matches a previous request file (see below), the client may be ending use of

file-based error recovery.

◆ If NEWFILEUID matches a previous request file, the client is requesting error recovery. The

server should send the matching saved response file.

Note: If NEWFILEUID matches a previous request file then the request file identified

by the NEWFILEUID must contain exactly the same set of transactions as the previous

request file. Servers can reject the file if it contains new or modified transactions. In

particular, clients should disallow new <PINCHRQ> transactions during error

recovery. For more information about <PINCHRQ> and synchronization, see section

2.5.2.

◆ If NEWFILEUID is not set to NONE and does not match a previous request file, the client is

preparing for error recovery. The server should save the response file in case the data does not

reach the client.

◆ If OLDFILEUID is set to NONE, the server may ignore the presence of this header. The server

should not search for a response file to delete. Clients should initiate file-based error recovery

by sending OLDFILEUID set to NONE and NEWFILEUID set to a unique value.

◆ If OLDFILEUID matches a file saved on the server, then OLDFILEUID is a file that the client

has successfully processed and the server can delete it.

◆ If OLDFILEUID is not set to NONE and does not match a previous request file, the server

should ignore the presence of this header. Either the server has purged the associated request

file without explicit request from the client or the client is requesting error recovery with

identical headers to the initial request attempt (NEWFILEUID should match a previous

request file in this case).

106 6.10 Synchronization Alternatives

Note: While it may indicate a client error for OLDFILEUID and NEWFILEUID to

hold identical values other than NONE, the server should ignore this OLDFILEUID

header. Earlier rules in this list detail how the server should handle the request file

(based solely upon the NEWFILEUID value).

A server should not save more than one file per client data file thread (history of FILEUID

values). Servers should purge response files in response to an explicit client request (reference in

the OLDFILEUID header) or after some long period (at least 2 months). Clients must not abuse

this storage requirement by (for example) setting OLDFILEUID to the header used three request

files previously. The server should preserve response files on a per-thread basis. This approach

would support multiple clients or data files per user. But, the server has the option to ignore

these needs and purge response files as soon as another valid request arrives for the same

<USERID>. In either case, if an error recovery attempt comes after the corresponding error

recovery file is purged, the server will not recognize the request as an attempt at error recovery.

The server would simply process it as a new request. In this case, the server should recognize

duplicate transaction UIDs for client-initiated work, such as payments, and then reject them

individually. Server-generated responses would be lost to the client.

A server should not save a response file when it is useless to do so. Specifically, the server should

not save a response file when the request fails parsing or when the request was rejected due to a

<SONRQ> problem (e.g. invalid <USERID>).

If all accounts are shared between two (or more) users (for example, husband and wife have

separate online access to the same list of joint accounts and none others), some identifiers may

differ and should be maintained separately by the client. Thus, clients should initiate error

recovery and maintain/generate xxxFILEUID values on a per-user basis.

6.10.1.1 File-Based Error Recovery and Authentication

There are two aspects of error recovery authentication which must be considered, request

validation and password validation.

6.10.1.1.1 Request Validation

When error recovery is being attempted the server should first perform signon authentication on

the request file. Once this is done, it should validate that the rest of the transactions in the request

file received match those of the request file that was archived for the corresponding response file

which was also archived. Recommended matching is defined at two levels:

◆ Minimal—Verify that the transactions correspond to the archived file

◆ Recommended—Verify the current request and archived request files exactly match. It is

recommended that checksums for all characters after the </SONRQ> be used to verify an

exact match. (The signon request itself may change between attempts.)

OFX 1.6 Specification 10710/18/99

6.10.1.1.2 Password Validation

In all cases, the server must not store response files for the purposes of file-based error recovery

when the <SONRQ> has failed. A saved response file matching the OLDFILEUID header (if any)

must not be deleted when this occurs.In error recovery situations, the possibility exists that the

user will have entered the correct password when a request was originally sent, but will mistype

the password when prompted for it again during the recovery attempt. The server should

respond as it would whenever sign on fails: It should return 15500 errors in all transaction

response aggregates. The server should return synchronization wrappers with <TOKEN>-1 and

any embedded transaction response aggregates with the same 15500 error. (The response file

should contain no <xxxRS> aggregates apart from the <SONRS>.) This particular situation (sign

on failure during an error recovery attempt) merits careful attention to the rules described in the

previous paragraph.

6.10.2 Lite Synchronization

Lite synchronization requires servers to accept all synchronization messages, but does not

require them to keep any history or tokens. Responses need to be sent only once and then the

server can forget them. Responses to client requests, whether or not they are made inside a

synchronization request, are processed normally. Responses that represent server-initiated work,

such as payment responses that arise from recurring payments, are sent only in response to

synchronization requests. A server does not have to hold responses in case a second client makes

a synchronization request.

Basic lite synchronization servers do not support <REFRESH>Y. These servers may implement

<TOKEN>0 responses as a pseudo-refresh (as described in section 6.10.2.1).

Refresh-capable lite

synchronizing servers, however, do support <REFRESH>Y. That, in fact, is the only difference in

function between a Basic Lite Synch server and a Refresh-capable Lite Synch Server. The purpose

of the distinction is to allow a server to provide refresh capability without the burden of

supporting full synchronization.

For a server accustomed to sending unsolicited responses, lite synchronization should closely

match the current implementation of file-based error recovery. The only difference is that a

server should hold the unsolicited responses until the client makes the first appropriate

synchronization request; rather than automatically adding them to any response file. Once

added, the server can mark them as delivered, relying on error recovery to ensure actual

delivery.

Note: OFX requires a server to authenticate a client in Error Recovery.

6.10.2.1 Lite Synchronization and <REFRESH>

Basic lite synchronization servers do not support <REFRESH>Y. These servers may implement

<TOKEN>0 responses as a pseudo-refresh. If a server does not support <REFRESH>Y requests,

they may still choose to respond to a <TOKEN>0 request as if <REFRESH>Y were requested. In

108 6.10 Synchronization Alternatives

this case, the response should be returned with a <TOKEN>1. This token never again increments

and would be handled as described in section 6.10.2

(returning only unsolicited responses). This

has the advantage of allowing all unsolicited responses to be discarded immediately after they

have been included in a <xxxSYNCRS> (with <TOKEN>1) response.

Refresh-capable Lite Synchronization servers may support both file-based error recovery and

<REFRESH>Y. OFX 1.0.2, 1.5.1, and 1.6 support Refresh-capable Lite Synchronization. (Existing

clients may ignore this new feature.)

For more information on profiling synchronization support, see section 7.2.1

6.10.3 Relating Synchronization and Error Recovery

Client and server developers should first decide whether or not they will support full

synchronization. If they can, then they can support file-based error recovery as well, or they can

rely on synchronization to perform error recovery. If they adopt only lite synchronization, OFX

requires file-based error recovery. A server describes each of these choices in its server profile

records. The following combinations are valid:

◆ Full synchronization with file-based error recovery

◆ Full synchronization without separate file-based error recovery

◆ Lite synchronization with file-based error recovery (with or without <REFRESH>Y support)

Clients request file-based error recovery by including the old and new session UIDs in the

header. If these are absent, servers need not save the response file for error recovery. Clients

request synchronization by using those synchronization requests defined throughout this

specification.

OFX 1.6 Specification 10910/18/99

6.11 Examples

Here is an example of full synchronization using bill payment as the service. OFX Payments

provides two different synchronization requests and responses, each with their own token; one

for payment requests and one for repeating payment model requests. Note that these simplified

examples do not include the outer <OFX> layer, <SONRQ>, and so forth.

Client A requests synchronization:

<TOKEN>123

<REJECTIFMISSING>N

<BANKID>121000248

<ACCTID>123456789

<ACCTTYPE>CHECKING

</BANKACCTFROM>

</PMTSYNCRQ>

The server sends in response:

<TOKEN>125

<LOSTSYNC>N

<BANKID>121000248

<ACCTID>123456789

<ACCTTYPE>CHECKING

</BANKACCTFROM>

<TRNUID>123

... status details

</STATUS>

<PMTRS>

... details on a payment response

</PMTRS>

</PMTTRNRS>

<TRNUID>546

... status details

</STATUS>

110 6.11 Examples

<PMTRS>

... details on another payment response

</PMTRS>

</PMTTRNRS>

</PMTSYNCRS>

Client A was missing two payment responses, which the server provides. At this point, client A

is synchronized with the server. Client A now makes a new payment request, and includes a

synchronization update as part of the request. This update avoids having to re-synchronize the

expected response at a later time.

<TOKEN>125

<REJECTIFMISSING>N

<BANKID>121000248

<ACCTID>123456789

<ACCTTYPE>CHECKING

</BANKACCTFROM>

<TRNUID>12345

<PMTRQ>

... details of a new payment request

</PMTRQ>

</PMTTRNRQ>

</PMTSYNCRQ>

The response to this new request:

<TOKEN>126

<LOSTSYNC>N

<BANKID>121000248

<ACCTID>123456789

<ACCTTYPE>CHECKING

</BANKACCTFROM>

... details on a payment response to the new request

</PMTTRNRS>

</PMTSYNCRS>

The client now knows that the server has processed the payment request it just made, and that

nothing else has happened on the server since it last synchronized with the server.

OFX 1.6 Specification 11110/18/99

Assume client B was synchronized with respect to payments for this account up through token

125. If it called in now and synchronized—with or without making additional requests—it

would pick up the payment response associated with token 126. It records the same information

that was in client A, which would give both clients a complete picture of payment status.

112 6.11 Examples

OFX 1.6 Specification 11310/18/99

CHAPTER 7 FI PROFILE

7.1 Overview

OFX clients use the profile to learn the capabilities of an OFX server. This information includes

general properties such as account types supported, user password requirements, specific

messages supported, and how the client should batch requests and where to send the requests. A

client obtains a portion of the profile when a user first selects an FI. The client obtains the

remaining information prior to sending any actual requests to that FI. The server uses a time

stamp to indicate whether the server has updated the profile, and the client checks periodically

to see if it should obtain a new profile.

In more detail, a profile response contains the following sections, which a client can request

independently:

◆ Message Sets – list of services and any general attributes of those services. Message sets are

collections of messages that are related functionally. They are generally subsets of what users

see as a service.

◆ Signon realms – FIs can require different signons (user ID and/or password) for different

message sets. Because there can only be one signon per <OFX> block, a client needs to know

which signon the server requires and then provide the right signon for the right batch of

messages.

The profile message is itself a message set. In files, OFX uses the <PROFMSGSETV1> and

<PROFMSGSETV2> aggregates to identify this profile message set.

The following sections describe the general use of profile information.

7.1.1 Message Sets

A message set may be thought of as representing an available financial service. A message set

itself is a collection of related messages. For example, Chapter 11, "

Banking," defines several

message sets: statement download, credit card statement download, intrabank transfers, and so

forth. A server may route all of the messages in a message set to a single URL and merge their

versions together.

Clients and servers generally use message sets as the granularity to decide what functionality

they will support. A “banking” server can choose to support the statement download and

intrabank transfer message sets, but not the wire transfer message set. Attributes are available in

many cases to further define how OFX supports a message set.

The profile applies only to the requests a client might expect the server to honor. That is, clients

should not send requests to servers unless support is indicated. However, the server may send

114 7.1 Overview

unsupported responses in a sync response as information is entered out of band. A client is

required to at least parse such a file.

Clients should assume the burden of checking the profile and not sending a transaction which

the server does not support. If the client goes ahead and sends such a transaction, the server

must ignore unrecognized and unsupported elements and aggregates within a request.

Assuming no other problems occur in processing that request, servers may return warning code

2028 (Request element unknown). In either case (an unrecognized transaction or unknown

elements or aggregates within a request), the response file should not contain the unrecognized

tags or the contents of unrecognized aggregates.

Each portion of the OFX specification that defines messages also defines the message set to

which those messages belong. This includes what additional attributes are available for those

messages and whether OFX requires the message set or it is optional.

7.1.2 Version Control

Message sets are the basis of version control. Over time there will be new versions of the message

sets, and at any given time servers will likely want to support more than one version of a

message set. Clients should also be capable of supporting as many versions as possible. Through

the profile, clients discover which versions are supported for each message set. Clients and

servers exchange messages at the highest common level for each message set.

The DTD used to parse the OFX document determines which message sets are supported. There

are currently three supported DTDs. OFX 1.5.1 and OFX 1.6 support all currently defined

message sets, and OFX 1.0.2 supports only version 1 message sets (except Bill Presentment). For

more information about DTD versions, see section 1.4

and 2.2.3.

There are two versions of the profile message set. Version 2 of the profile message set allows

additional options specific to the corresponding request and response wrappers. The

<MSGSETCORE> aggregate may include a longer <URL2> element and the <COUNTRY>

element when used in version 2 of the profile message set.

If banking version 1 is at one URL (A) and billpay version 1 is at another URL (B), both may need

version 1 of signon to be used. In that case, <MSGSETCORE> inside <BANKMSGSETV1> would

refer to <URL>A and <MSGSETCORE> inside <BILLPAYMSGSETV1> would refer to <URL>B,

but <MSGSETCORE> inside <SIGNONMSGSETV1>may refer to either URL or to some other.

As mentioned in Section 2.5.4

, the <URL> included in <SIGNONMSGSETV1> does not restrict

where the <SIGNONMSGSRQV1> wrapper may be sent.

OFX 1.6 Specification 11510/18/99

7.1.3 Batching and Routing

To allow FIs to set up different servers for different message sets, different versions, or to directly

route some messages to third party processors, message sets define the URL to which a server

sends messages in that message set. Each version of a message set can have a different URL. In

the common case where many or all message sets are sent to a single URL, clients will

consolidate messages across compatible message sets. Clients may consolidate when all of the

following are true:

◆ Message sets have the same URL;

◆ Message sets have a common security level; and

◆ Message sets have the same signon realm.

Note: Signon messages can be sent with all other message sets even if the

<SIGNONMSGSET> contains incompatible settings for the URL, security level, or

signon realm. The message set information for signon messages is used only if the

signon message is sent by itself. Otherwise, the settings are inherited from the

accompanying service message set.

The same message set may be supported by multiple servers. In this case, each server that

supports a particular message set must have a unique URL.

7.1.4 Client Signon for Profile Requests

Clients must include a signon request <SONRQ> with every message, including profile requests.

The first time that a client requests the FI profile, the signon request will be present, but the user

ID and password will not be valid and will be ignored by the server.

Note: Since elements cannot be set to a blank value, <USERID> and/or <USERPASS>

may be set to lower case “anonymous” followed by 23 zeroes.

Once the user has enrolled and received his or her user ID and password, the client must request

the profile again, even if the profile is not yet out-of-date. Once it has received a successful

<PROFRS> (with or without a profile download) while signed on as the user, the client must not

At this point, the server can respond with a profile response that indicates that the profile is up-

to-date or return a new FI profile in response. If the FI wants to return a customer-specific profile,

the FI must use the second approach. Servers must handle <PROFRQ> without an error whether

or not a request arrives with an anonymous <SONRQ>.

Note: OFX 1.0.2 clients and servers may violate these restrictions, which were added

in later versions. Clients interacting with 1.0.2 servers should gracefully handle

<PROFRS> errors in their first per-user attempt, reverting to anonymous requests for

subsequent requests (until the next response with <STATUS><CODE>0, when they

should once again make a per-user attempt to retrieve the profile). Servers interacting

116 7.1 Overview

with 1.0.2 clients should not require support for customer-specific profiles. Servers

correcting problems with per-user <PROFRQ> requests (which previously caused

error responses) must update the FI Profile to tell compliant clients to retry.

For more information about signon requests, refer to section 2.5

7.1.5 Profile Request <PROFRQ>

A profile request indicates which profile components a client desires. It also indicates what the

client’s routing capability is. Profiles returned by the FI must be compatible with the requested

routing style, or the server returns an error.

Profile requests are not subject to synchronization.

Profile requests must appear within a <PROFTRNRQ> transaction wrapper.

The SERVICE option supports clients that can route bill payment messages to a separate URL

from the rest of the messages. Because the exact mapping of message sets to the general concept

of bill payment can vary by client and by locale, this specification does not provide precise rules

for the SERVICE option. Each client will define its requirements.

Tag Description

Profile-request aggregate

Identifies client routing capabilities, see table below

Date and time client last received a profile update, datetime

</PROFRQ>

Tag Description

NONE Client cannot perform any routing. All URLs must be the same. All message sets

share a single signon realm.

SERVICE Client can perform limited routing. See details below.

MSGSET Client can route at the message-set level. Each message set can have a different

URL and/or signon realm.

OFX 1.6 Specification 11710/18/99

7.2 Profile Response <PROFRS>

To determine whether the client has the latest version of the FI profile, the server checks the date

and time passed by the client in <DTPROFUP>.

If the client has the latest version of the FIs profile, the server returns status code 1 in the

<STATUS> aggregate of the profile-transaction aggregate <PROFTRNRS>. The server does not

return a profile-response aggregate <PROFRS>.

Note: Not sending a response aggregate in this case is an exception to rules outlined

in sections 2.4.6

and 3.1.5.

If the client does not have the latest version of the FI profile, the server responds with the profile-

response aggregate <PROFRS> in the profile-transaction aggregate <PROFTRNRS>. The

response includes message set descriptions, signon information, and general contact

information.

Tag Version Description

Profile-response aggregate

Beginning list of message set information

xxxMSGSET

One or more message set aggregates

</xxxMSGSET>

</MSGSETLIST>

Beginning of signon information

Zero or more signon information aggregates.

Though the DTD allows an empty <SIGNONINFOLIST>,

servers should profile at list one signon realm (include a

minimum of one <SIGNONINFO> aggregate in the

<PROFRS> response).

</SIGNONINFO>

</SIGNONINFOLIST>

Time this was updated on server, datetime

Name of institution, A-32

<ADDR1>

FI address, line 1, A-32

<ADDR2>

FI address, line 2, A-32

<ADDR3>

FI address, line 3. Use of <ADDR3> requires the presence of

<ADDR2>, A-32

<CITY>

FI address city, A-32

<STATE>

FI address state, A-5

118 7.2 Profile Response <PROFRS>

7.2.1 Message Set

An aggregate describes each message set supported by an FI. Message sets in turn contain an

aggregate for each version of the message set that is supported. For a message set named xxx, the

convention is to name the outer aggregate <xxxMSGSET> and the tag for each version

<xxxMSGSETVn>. The reason for message set-specific aggregates is that the set of attributes

depends on the message set. These can change from version to version, so there are version-

specific aggregates as well.

The general form of the response is:

FI address postal code, A-11

FI address country; 3-letter country code from ISO/DIS-

3166, A-3

Customer service telephone number, A-32

Technical support telephone number, A-32

Fax number, A-32

<URL>

V1 only URL for general information about FI (not for sending

data), URL

<URL2>

V2 only URL for general information about FI (not for sending

data), URL2

V2 only Whether or not the returned URL is a redirection URL.

Boolean

<EMAIL>

E-mail address for FI, A-80

</PROFRS>

Tag Description

xxxMSGSET

Service aggregate

xxxMSGSETVn

Version-of-message-set aggregate, <xxxMSGSETV1> is required.

<xxxMSGSETV2> may appear zero or more times. As mentioned in Sections

14.7.2

and 14.7.3, <PRESDIRMSGSETV1> and <PRESDLVMSGSETV1> may

appear one or more times.

xxxMSGSETVn

xxxMSGSET

Tag Version Description

OFX 1.6 Specification 11910/18/99

The <

xxx

MSGSETVn> aggregate has the following form:

The common message set information <MSGSETCORE> is as follows:

Tag Description

xxx

MSGSETVn>

Message-set-version aggregate

Common message set information aggregate.

</MSGSETCORE>

Message-set

specific

Zero or more attributes specific to this version of this message set, as defined

by each message set

xxx

MSGSETVn>

Tag Version Description

Common-message-set-information aggregate

<VER>

Version number of the message set, (for example, <VER>1 for

version 1 of the message set), N-5

Because this information is already provided by the surrounding

<xxxMSGSETVn> wrapper, <VER> should be ignored by OFX

clients. Nonetheless, servers should use one of the supported

values (<VER>1 or <VER>2) consistent with that wrapper.

<URL>

V1 only URL where messages in this set are to be sent, URL

<URL2>

V2 only URL where messages in this set are to be sent, URL2

Security level required for this message set; see Chapter 4, "OFX

Security." NONE or TYPE 1.

Y if transport-level security must be used, N if not used; see

Chapter 4, "

OFX Security." Boolean

Signon realm to use with this message set, A-32

1 or more.

Language supported, language.

If more than one language is supported, multiple <LANGUAGE>

elements can be sent.

120 7.2 Profile Response <PROFRS>

V2 only 0 or more.

Prefix of country-specific elements supported and field

interpretations: 3-letter country code from ISO/DIS-3166.

If multiple <COUNTRY> elements are present, then multiple

countries are supported. If this field is missing, then it is assumed

that only the USA version of OFX is supported. For example, if the

values “FRA” and “ITA” are present, then the server supports the

French and Italian “versions” of OFX. If a country is supported for

any of the main message sets, then the server should accept a

signon request for that country. Otherwise, the server should reject

such a signon request.

The following countries are currently supported in OFX:

COUNTRY

BEL

CAN

CHE

DEU

ESP

FRA

GBR

ITA

NLD

USA

Country Name

Belgium

Canada

Switzerland

Germany

Spain

France

Great Britain

Italy

Netherlands

United States of America

FULL for full synchronization capability

LITE for lite synchronization capability

See Chapter 6, "

Data Synchronization," for more information.

1.6 add Y if server supports <REFRESH>Y within synchronizations. This

option is irrelevant for full synchronization servers. Clients must

ignore <REFRESHSUPT> (or its absence) if the profile also specifies

<SYNCMODE>FULL. For lite synchronization, the default is N.

Without <REFRESHSUPT>Y, lite synchronization servers are not

required to support <REFRESH>Y requests, Boolean

Y if server supports file-based error recovery, Boolean

See Chapter 6, "

Data Synchronization," for more information.

Service provider name, A-32

Some financial institutions out-source their OFX servers to a service

provider. In such cases, the SPNAME element should be included

in the MSGSETCORE.

</MSGSETCORE>

Tag Version Description

OFX 1.6 Specification 12110/18/99

Note: For all message sets currently defined in OFX, <TRANSPSEC>Y must be

specified.

Note: Within a <MSGSETCORE> aggregate, the <VER> element defines the version

number of that message set. It does not refer to the version number of the OFX

specification or the DTD files. For more information about message sets and version

numbers, refer to section 2.4.5.

Note: Within a message set, there can be more than one <MSGSETCORE> aggregate

with the same value for <VER>, or the same value for <URL>, but not the same value

for both. The pair must be unique for each instance of <MSGSETCORE> within a

message set. Multiple <MSGSETCORE>s with the same value for <VER> are used in

instances such as signon or registration, which may have the same version sent to

multiple URLs for different services.

7.2.2 Signon Realms

A signon realm identifies a set of messages that can be accessed using the same password.

Realms are used to disassociate signons from specific services, allowing FIs to require different

signons for different message sets. In practice, FIs will want to use the absolute minimum

number of realms possible to reduce the user’s workload.

Tag Version Description

Signon-information aggregate

Identifies this realm, A-32

<MIN>

Minimum number of password characters, N-2

<MAX>

Maximum number of password characters, N-2

Type of characters allowed in password:

ALPHAONLY Password may not contain numeric

characters. The server would allow

“abbc”, but not “1223” or “a122”.

NUMERICONLY Password may not contain alphabetic

characters. The server would allow

“1223”, but not “abbc” or “a122”.

ALPHAORNUMERIC Password may contain alphabetic or

numeric characters (or both). The

server would allow “abbc”, “1223”, or

“a122”.

ALPHAANDNUMERIC Password must contain both

alphabetic and numeric characters.

The server would allow “a122”, but

not “abbc” or “1223”.

122 7.2 Profile Response <PROFRS>

7.2.3 Status Codes

Y if password is case-sensitive, Boolean

Y if special characters are allowed over and above those characters

allowed by <CHARTYPE> and <SPACES>, Boolean

Y if spaces are allowed over and above those characters allowed by

<CHARTYPE> and <SPECIAL>, Boolean

<PINCH>

Y if server supports <PINCHRQ> (PIN change requests), Boolean

Y if server requires clients to execute <PINCHRQ> as part of first

signon. Clients must ignore <CHGPINFIRST> if the profile also

specifies <PINCH>N. Boolean

V2 only The type of password(s) supplied by the client in the signon

request to authenticate the user (see section 2.5.1.1

). The following

password types are currently supported in OFX:

PWTYPE

Description

FIXED The client supplies (in USERPASS) a

normal password that remains fixed

until explicitly changed by the user or

the FI. This is the default password

type. Clients should assume FIXED

password type when <PWTYPE> is

not present in <SIGNONINFO>.

ONETIME In addition to USERPASS, the client

supplies (in ONETIMEPASS) an

additional password that was taken

from a list of one-time passwords sent

from the FI to the user.

HWTOKEN In addition to USERPASS, the client

supplies (in ONETIMEPASS) an

additional password that was

generated by a hardware token such

as a crypto-calculator, typically on a

time-varying basis.

</SIGNONINFO>

Value Meaning

0 Success (INFO)

1 Client is up-to-date (INFO)

2000 General error (ERROR)

Tag Version Description

OFX 1.6 Specification 12310/18/99

7.3 Profile Message Set Profile Information

The profile message set functions the same way as all other message sets; therefore, it contains a

profile description for that message set. Because <PROFMSGSET> is always part of a message

set response, it is described here. Servers must include the <PROFMSGSET> as part of the profile

response <MSGSETLIST>. There are no attributes, but the aggregate must be present to indicate

support for the message set.

Tag Description

Message-set-profile-information aggregate

Opening tag for V1 of the message set profile information

Common message set information

</MSGSETCORE>

</PROFMSGSETV1>

Opening tag for V2 of the message set profile information

Common message set information

</MSGSETCORE>

</PROFMSGSETV2>

</PROFMSGSET>

124 7.3 Profile Message Set Profile Information

OFX 1.6 Specification 12510/18/99

CHAPTER 8 ACTIVATION & ACCOUNT INFORMATION

8.1 Overview

The Signup message set defines three messages to help users get setup with their FI:

◆ Enrollment – informs FI that a user wants to use OFX and requests that a password be

returned

◆ Accounts – asks the FI to return a list of accounts and the services supported for each account

◆ Activation – allows a client to tell the FI which services a user wants on each account

There is also a message to request name and address changes.

Clients use the account information request on a regular basis to look for changes in a user’s

account information. A time stamp is part of the request so that a server has to report only new

changes. Account activation requests are subject to data synchronization, and will allow multiple

clients to learn how the other clients have been enabled.

In OFX request files, the <SIGNUPMSGSRQV1> and <SIGNUPMSGSRQV2> aggregates identify

the Signup messages.

8.1.1 Sign-Up Message Set V2 and Proxy On-Behalf-Of Actions

In OFX 1.6, the Sign-Up Message Set V2 can act on behalf of a user other than the one specified in

<SONRQ> by specifying an optional <USERID> in <SIGNUPMSGSRQV2> before the

<xxxTRNRQ> and/or <xxxSYNCRQ>. It is the server's responsibility to ensure that the user

specified in <SONRQ> has the authority to act on behalf of the user specified in

<SIGNUPMSGSRQV2>.

Note: The server must indicate support for <USERID> by including

<CANSUPPORTUSERID>Y in the <SIGNUPMSGSETV2> message. See section 8.8

If a <USERID> is specified in <SIGNUPMSGSRQV2>, then all transactions within that message

set wrapper are to be performed on behalf of the user identified by that <USERID>. Therefore, if

a single OFX block is to contain transactions on behalf of several users, each user will require its

own <SIGNUPMSGSRQV2> (for example, multiple user activations as mentioned in section

8.2.1

). The response message set wrapper <SIGNUPMSGSRSV2> echoes the <USERID> if it is

supplied by the corresponding request message set wrapper.

126 8.2 Approaches to User Sign-Up with OFX

8.1.1.1 Sign-Up Message Set Wrapper Request

8.1.1.2 Sign-Up Message Set Wrapper Response

8.2 Approaches to User Sign-Up with OFX

The message sets in this chapter are designed to allow both FIs and clients to support a variety of

sign-up procedures. There are four basic steps a user needs to go through to complete the sign-

up:

1. Select the FI. OFX does not define this step or provide message sets to support it. Client

developers and FIs can let a user browse or search this information on a web site, or might

define additional message sets to do this within the client. At the conclusion of this step, the

client will have some minimal profile information about the FI, including the set of services

supported and the URL to use for the next step.

2. Enrollment and password acquisition. In this step, the user identifies and authenticates

itself to the FI without a password. In return, the user obtains a password (possibly temporary)

to use with OFX. FIs can perform this entire step over the telephone, through a combination

of telephone requests and a mailed response, or at the FI web site. FIs can also use the OFX

enrollment message to do this by means of the client. The response can contain a temporary

password or users can wait for a mailed welcome letter containing the password.

3. Account Information. In this step, the user obtains a list of accounts available for use with

OFX, and which specific services are available for each account. Even if users have enrolled

over the telephone, clients will still use this message set to help users properly set up the

accounts within the client. Clients periodically check back with the FI for updates.

Tag Version Description

Sign-Up Message Set Wrapper Request

1.6 add On-Behalf-Of User, A-32

xxxyyy

RQ>

Zero or more transaction and/or synchronization requests

xxxyyy

RQ>

</SIGNUPMSGSRQV2>

Tag Version Description

Sign-Up Message Set Wrapper Response

1.6 add On-Behalf-Of User, A-32

xxxyyy

RS>

Zero or more transaction and/or synchronization responses

xxxyyy

RS>

</SIGNUPMSGSRSV2>

OFX 1.6 Specification 12710/18/99

4. Service Activation. The last step is to activate specific services on specific accounts. The

activation messages support this step. Synchronization is applied to these messages to ensure

that other clients are aware of activated services.

The combination of media-interface through which an FI accomplishes these steps can vary. FIs

might wish to do steps two through four over the telephone. Clients will still use OFX messages

in steps 3 and 4 to automatically set up the client based on the choices made by the user over the

phone. Other FIs might wish to have the entire user experience occur within the client. Either

way, the OFX sign-up messages support the process.

8.2.1 Multiple User Enrollment and Activation

Clients may enroll multiple users in a single <SIGNUPMSGSRQV2> (but not V1). This

eliminates the need for a separate round-trip or message set wrapper for each user to be enrolled.

In such a case, the client sends an <ENROLLRQ> for each user. Note that this cannot be used in

conjunction with rapid signup (see section 8.2.2

), so no other transactions may be included with

the series of <ENROLLRQ>s.

Clients that want to send multiple account activations for multiple users, can send multiple

<SIGNUPMSGSRQV2>s in a single OFX block, with <USERID> specified in each message set

wrapper.

In multiple enrollments and multiple activations, the server can process the individual requests

in any order.

8.2.2 Rapid Signup

Clients may include multiple <ACCTRQ>s in a <SIGNUPMSGSRQV2> (but not V1) that

contains an <ENROLLRQ>. This allows the client to combine steps two through four, as outlined

above, in a single round trip. In such a case, the <ENROLLRQ> must be the first request in the

message set wrapper, and the other transactions apply to that newly enrolled user. When rapid

signup is used, the server must process the transactions in the same order as they appear in the

message set wrapper. If the enrollment fails, the other transactions need not be processed;

however, they must return a status code of 13500.

128 8.3 Users and Accounts

8.3 Users and Accounts

To support the widest possible set of FIs, OFX assumes that individual users and accounts are in

a many-to-many relationship. Consider a household with three accounts:

◆ Checking 1 – held individually by one spouse

◆ Checking 2 – held jointly by both

◆ Checking 3 – held individually by the other spouse

Checking 2 should be available to either spouse, and the spouse holding Checking 1 should be

able to see both Checking 1 and 2.

OFX expects FIs to give each user their own user ID and password. Each user will go through the

enrollment step separately. A given account need only be activated once for a service; not once

for each user. Clients will use the account information and activation messages to combine

information about jointly held accounts.

If an FI prefers to have a single user ID and password per household or per master account, it

will have to make this clear to users through the enrollment process. It is up to the FI to assign a

single user ID and password that can access all three of the checking accounts described above.

8.4 Enrollment and Password Acquisition

The main purpose of the enrollment message is to communicate a user’s intent to access the FI by

way of OFX and to acquire a password for future use with OFX. Some FIs might return a user ID

and an initial password in the enrollment response, while others will send them by way of

regular mail.

Note: The client may not know the user ID and password when it sends the

enrollment request, in such a case the <USERID> and/or <USERPASS> may be set to

lower case “anonymous” followed by 23 zeroes.

Enrollment requests are not subject to synchronization. If the client does not receive a response, it

will simply re-request the enrollment. If a user successfully enrolls from another client before the

first client obtains a response, the server should respond to subsequent requests from the first

client with status code:

13501 - user already enrolled.

OFX 1.6 Specification 12910/18/99

8.4.1 User IDs

The OFX <SONRQ> requires a user ID to uniquely identify a user to an FI. The server must

accept the user ID with or without punctuation.

Many FIs in the United States use social security numbers (SSNs) as the ID. Others create IDs

that are unrelated to the users’ SSNs. Some FIs have existing user IDs that they use for other

online activities that they want to use for OFX as well. FIs might also create new IDs specifically

for OFX. Finally, some FIs might assign IDs while others might allow users to create them.

Because users do not usually know either their OFX sign-on user ID or their password at time of

enrollment, the enrollment response is designed to return both. The enrollment request allows

users to optionally provide a user ID, which an FI can interpret as their existing online ID or a

suggestion for what their new user ID should be. Ideally, the enrollment process should explain

ID syntax to users.

8.4.2 Enrollment Request <ENROLLRQ>

The enrollment request captures enough information to identify and authenticate a user as being

legitimate and that it has a relationship with the FI.

FIs might require that an account number be entered as part of the identification process.

However, this is discouraged since the account information request is designed to automatically

obtain all account information, avoiding the effort and potential mistakes of a user-supplied

account number.

It is RECOMMENDED that FIs provide detailed specifications for user IDs and passwords

along with information about the services available when a user is choosing an FI.

130 8.4 Enrollment and Password Acquisition

The enrollment request must appear within an <ENROLLTRNRQ> transaction wrapper.

This enrollment request is intended for use only by individuals. Business enrollment will be

defined in a later release.

Tag Version Description

Enrollment-request aggregate

First name of user, A-32

Middle name of user, A-32

Last name of user, A-32

<ADDR1>

Address line 1, A-32

<ADDR2>

Address line 2, A-32

<ADDR3>

Address line 3. Use of <ADDR3> requires the presence

of <ADDR2>, A-32

<CITY>

City, A-32

<STATE>

State or province, A-5

Postal code, A-11

3-letter country code from ISO/DIS-3166, A-3

Daytime telephone number, A-32

Evening telephone number, A-32

<EMAIL>

Electronic e-mail address, A-80

Actual user ID if already known, or preferred user ID if

user can choose, A-32

<TAXID>

ID used for tax purposes (such as SSN), may be same as

user ID, A-32

Mother’s maiden name or equivalent, A-32

Date of birth, date

xxx

ACCTFROM>

An account description aggregate for an existing

account at the FI, for identification purposes only. For

example, <BANKACCTFROM> or <INVACCTFROM>.

xxx

ACCTFROM>

</ENROLLRQ>

OFX 1.6 Specification 13110/18/99

8.4.3 Enrollment Response <ENROLLRS>

The main purpose of the enrollment response is to acknowledge the request. In those cases

where FIs permit delivery of an ID and a temporary password, the response also provides for

this. Otherwise the server will send the real response to the user by way of regular mail,

electronic mail, or over the telephone. If enrollment is successful, but the server does not return

the ID and password in the response, a server is REQUIRED to use status code 13000 and

provide some information to the user by means of the <MESSAGE> element in the <STATUS>

aggregate about what to expect next.

The enrollment response must appear within an <ENROLLTRNRS> transaction wrapper.

Tag Description

Enrollment-response aggregate

Temporary password, A-32

User ID, A-32

Time the temporary password expires (if <TEMPPASS> included),

datetime

</ENROLLRS>

132 8.4 Enrollment and Password Acquisition

8.4.4 Enrollment Status Codes

8.4.5 Examples

An enrollment request:

<TRNUID>12345

<FIRSTNAME>Joe

<MIDDLENAME>Lee

<LASTNAME>Smith

<ADDR1>21 Main St.

<CITY>Anytown

<STATE>TX

<POSTALCODE>87321

<COUNTRY>USA

<DAYPHONE>123-456-7890

<EVEPHONE>987-654-3210

<EMAIL>jsmith@isp.com

<USERID>jls

<TAXID>123-456-1234

<SECURITYNAME>jbmam

<DATEBIRTH>19530202

</ENROLLRQ>

</ENROLLTRNRQ>

Code Meaning

0 Success (INFO)

2000 General error (ERROR)

13000 User ID & password will be sent out-of-band (INFO)

13500 Unable to enroll user (ERROR)

13501 User already enrolled (ERROR)

15508 Transaction not authorized (ERROR)

OFX 1.6 Specification 13310/18/99

And the reply might be:

<TRNUID>12345

<CODE>0

<SEVERITY>INFO

</STATUS>

<TEMPPASS>changeme

<USERID>jls

<DTEXPIRE>19970105

</ENROLLRS>

</ENROLLTRNRS>

8.5 Account Information

Account information requests ask a server to identify and describe all of the accounts accessible

by the signed-on user. The definition of all is up to the FI. At a minimum, it is RECOMMENDED

that a server include information about all accounts that it can activate for one or more OFX

services. To give the user a complete picture of his relationship with an FI, FIs can give

information on other accounts, even if those accounts are available only for limited OFX services.

Some service providers do not have prior knowledge of user account information. The profile

allows these servers to report this, and clients then know to ask users for account information

rather than reading it from the server.

Clients can perform several tasks for users with this account information. First, the information

helps a client set up a user for online services by giving it a precise list of its account information

and available services for each. Clients can set up their own internal state as well as prepare

service activation requests with no further typing by users. This can eliminate data entry

mistakes in account numbers, routing transit numbers, and so forth.

Second, FIs can provide limited information on accounts that would not ordinarily be suitable to

OFX services. For example, a balance-only statement download would be useful for certificates

of deposits even though a customer or an FI might not want or allow CDs to be used for full

statement download.

For each account, there is one <ACCTINFO> aggregate returned. The aggregate includes one

service-specific account information aggregate for each service available to that account. That, in

turn, provides the service-specific account identification. Common to each service-specific

account information aggregate is the <SVCSTATUS> element, which indicates the status of this

service on this account.

134 8.5 Account Information

A server should return joint accounts (accounts for which more than one user ID can be used to

access the account) for either user.

Requests and responses include a <DTACCTUP> element. Responses contain the last time a

server updated the information. Clients are REQUIRED to send this in a subsequent request, and

servers are REQUIRED to compare this to the current modification time and only send

information if it is more recent. The server sends the entire account information response if the

client’s time is older; there is no attempt to incrementally update specific account information.

<ACCTINFORS> should not be sent when the client is up-to-date.

Note: Not sending a response aggregate in the case of <ACCTINFORS> is an

exception to the rules outlined in 2.4.6

and 3.1.5.

8.5.1 Request <ACCTINFORQ>

The <ACCTINFORQ> request must appear within an <ACCTINFOTRNRQ> transaction

wrapper.

Tag Version Description

Account-information-request aggregate

Last <DTACCTUP> received in a response, datetime

<SVC2>

1.6 add Zero or more. Services to be included in

<ACCTINFORS>. The server has the option of ignoring

this element and returning information about all

services.

BANKSVC = Banking service

BPSVC = Payment service

INVSVC = Investments

PRESSVC = Bill Presentment service

</ACCTINFORQ>

OFX 1.6 Specification 13510/18/99

8.5.2 Response <ACCTINFORS>

The <ACCTINFORS> response must appear within an <ACCTINFOTRNRS> transaction

wrapper.

Tag Description

Account-information-response aggregate

Date and time of last update to this information on the server, datetime

Zero or more account information aggregates

Left out of the response when nothing is found (in the specified <SVC2>,

if any) for the current user.

Note: When <DTACCTUP> indicates the client is up-to-date, server

should not return surrounding <ACCTINFORS>.

</ACCTINFO>

</ACCTINFORS>

End of account information response

136 8.5 Account Information

8.5.3 Account Information Aggregate <ACCTINFO>

Note: A server uses the <DESC> field to convey the FI’s preferred name for the

account, such as “PowerChecking.” It should not include the account number.

8.5.4 Status Codes

Tag Version Description

Account-information-record aggregate

<DESC>

Description of the account, A-80

<PHONE>

Telephone number for the account, A-32

Service-specific account information, defined in each

service chapter. Some services may include additional

elements. Refer to service chapters for details.

Service-specific account identification. For a given

service xxx, there can be at most one

<xxxACCTINFO> returned. For example, you cannot

return two <BANKACCTINFO> aggregates.

</xxxACCTFROM>

V1 only AVAIL = Available, but not yet requested

PEND = Requested, but not yet available

ACTIVE = In use

V2 only AVAIL = Available, but not yet requested

PEND = Requested, but not yet available

ACTIVE = In use

REJECTED = Rejected

V2 only This element is only relevant if

<SVCSTATUS2>REJECTED is specified, A-255

</xxxACCTINFO>

</ACCTINFO>

Code Meaning

0 Success (INFO)

1 Client is up-to-date (INFO)

2000 General error (ERROR)

OFX 1.6 Specification 13710/18/99

8.5.5 Examples

An account information request:

<TRNUID>12345

</ACCTINFOTRNRQ>

And a response for a user with access to one account, supporting banking:

<TRNUID>12345

<CODE>0

<SEVERITY>INFO

</STATUS>

<DTACCTUP>19960102

<DESC>Power Checking

<PHONE>8002223333

<BANKID>1234567789

<ACCTID>12345

<ACCTTYPE>CHECKING

</BANKACCTFROM>

<SUPTXDL>Y

<XFERSRC>Y

<XFERDEST>Y

<SVCSTATUS>ACTIVE

</BANKACCTINFO>

</ACCTINFO>

</ACCTINFORS>

</ACCTINFOTRNRS>

138 8.6 Service Activation

8.6 Service Activation

Clients inform FIs that they wish to start, modify, or terminate a service for an account by

sending service activation requests. These are subject to data synchronization, and servers

should send responses to inform clients of any changes, even if the changes originated on the

server.

Clients use these records during the initial user sign-up process. Once a client learns about the

available accounts and services (by using the account information request above, or by having a

user directly enter the required information), it sends a series of service ADD requests.

If a user changes any of the identifying information about an account, the client sends a service

activation request containing both the old and the new account information. Servers should

interpret this as a change in the account, not a request to transfer the service between two

existing accounts, and all account-based information such as synchronization tokens should

continue. If a user or FI is reporting that a service should be moved between two existing

accounts, service must be terminated for the old account and started for the new account. The

new account will have reset token histories, as with any new service.

Each service to be added, changed, or removed is contained in its own request because the same

real-world account might require different <xxxACCTFROM> aggregates depending on the type

of service.

OFX 1.6 Specification 13910/18/99

8.6.1 Activation Request <ACCTRQ>

The <ACCTRQ> request must appear within an <ACCTTRNRQ> transaction wrapper.

8.6.1.1 Service Add Aggregate <SVCADD>

When a client sends a <SVCADD> to a financial institution routing particular messages to

another service provider, it is up to the financial institution to determine whether or not an

<ENROLLRQ> needs to be sent to the service provider along with the <SVCADD>. The FI may

choose to always send an <ENROLLRQ> and ignore the 13550 error message responses, though

this would only be reliable if <xxxACCTFROM> is included in the <ENROLLRQ>. The FI may

also choose to keep a database of enrolled services, so as to send an <ENROLLRQ> only when

the client is sending a <SVCADD> for a new service. The FI also has the option of sending

Tag Version Description

Account-service-request aggregate

Action identification. Specify

either <SVCADD>,

Action aggregate, either <SVCADD>, <SVCCHG>, or

</SVCCADD>

-or-

Service-addition aggregate

</SVCCHG>

-or-

Service-change aggregate

</SVCDEL>

Service-deletion aggregate

<SVC>

V1 only Service to be added/changed/deleted

BANKSVC = Banking service

BPSVC = Payments service

INVSVC = Investments

<SVC2>

V2 only Service to be added/changed/deleted

BANKSVC = Banking service

BPSVC = Payments service

INVSVC = Investments

PRESSVC = Bill Presentment service

</ACCTRQ>

140 8.6 Service Activation

<ENROLLRQ>s to all service providers when the client sends the initial <ENROLLRQ> to the

FI.

8.6.1.2 Service Change Aggregate <SVCCHG>

8.6.1.3 Service Delete Aggregate <SVCDEL>

Tag Version Description

Service-addition aggregate

xxx

ACCTTO

Service-specific-account-identification aggregate (for example,

<BANKACCTTO> or <INVACCTTO>)

xxx

ACCTTO>

V2 only A token provided out-of-band by an FI or biller to speed up

activation of the account, A-32

</SVCADD>

Tag Description

Service-change aggregate

xxx

ACCTFROM>

Service-specific-account-identification aggregate (for example,

<BANKACCTFROM> or <INVACCTFROM>)

xxx

ACCTFROM>

xxx

ACCTTO>

Service-specific-account-identification aggregate (for example,

<BANKACCTTO> or <INVACCTTO>)

xxx

ACCTTO>

</SVCCHG>

Tag Description

Service-deletion aggregate

xxx

ACCTFROM>

Service-specific-account-identification aggregate (for example,

<BANKACCTFROM> or <INVACCTFROM>)

xxx

ACCTFROM>

</SVCDEL>

OFX 1.6 Specification 14110/18/99

8.6.2 Activation Response <ACCTRS>

The <ACCTRS> response must appear within an <ACCTTRNRS> transaction wrapper.

Tag Version Description

Account-service-response aggregate

Action identification. Specify

either <SVCADD>,

</SVCADD>

-or-

Service-addition aggregate

</SVCCHG>

-or-

Service-change aggregate

</SVCDEL>

Service-deletion aggregate

<SVC>

V1 only Service to be added/changed:

BANKSVC = Banking service

BPSVC = Payments service

INVSVC = Investments

<SVC2>

V2 only Service to be added/changed:

BANKSVC = Banking service

BPSVC = Payments service

INVSVC = Investments

PRESSVC = Bill Presentment service

V1 only AVAIL = Available, but not yet requested

PEND = Requested, but not yet available

ACTIVE = In use

V2 only AVAIL = Available, but not yet requested

PEND = Requested, but not yet available

ACTIVE = In use

REJECTED = Rejected

V2 only This element is only relevant if

<SVCSTATUS2>REJECTED is specified, A-255

</ACCTRS>

142 8.6 Service Activation

8.6.3 Status Codes

Code Meaning

0 Success (INFO)

2000 General error (ERROR)

2002 General account error (ERROR)

2006 Source account not found (ERROR)

2007 Source account closed (ERROR)

2008 Source account not authorized (ERROR)

2009 Destination account not found (ERROR)

2010 Destination account closed (ERROR)

2011 Destination account not authorized (ERROR)

6502 Unable to process embedded transaction due to out-of-date

<TOKEN> (ERROR)

13502 Invalid service (ERROR)

15508 Transaction not authorized (ERROR)

OFX 1.6 Specification 14310/18/99

8.6.4 Service Activation Synchronization

Service activation requests are subject to the standard data synchronization protocol. The scope

of these requests and the <TOKEN> is the user ID. The request and response tags are

<ACCTSYNCRQ> and <ACCTSYNCRS>.

8.6.4.1 Request <ACCTSYNCRQ>

Tag Version Description

Activation synchronization request aggregate

Client synchronization

option; <TOKEN>,

<TOKEN2>,

<TOKENONLY>, or

<TOKEN>

V1 only Previous value of <TOKEN> received for this type of

synchronization request from server; 0 for first-time requests;

token

V2 only Previous value of <TOKEN2> received for this type of

synchronization request from server; 0 for first-time requests;

token2

Request for just the current <TOKEN> without the history,

Boolean

Request for refresh of current state, Boolean

If Y, do not process requests if client <TOKEN> is out of date,

Boolean

Account-service-request transactions (0 or more)

</ACCTTRNRQ>

</ACCTSYNCRQ>

144 8.6 Service Activation

8.6.4.2 Response <ACCTSYNCRS>

Tag Version Description

Payee-list-request aggregate

<TOKEN>

V1 only New synchronization token, token

V2 only New synchronization token, token2

Y if the token in the synchronization request is older than the

earliest entry in the server’s history table. In this case, some

responses have been lost.

N if the token in the synchronization request is newer than or

matches a token in the server’s history table. Boolean

V2 only Optional error code (See section 6.4.4.), N-6.

Account-service-response transactions (0 or more)

</ACCTTRNRS>

</ACCTSYNCRS>

OFX 1.6 Specification 14510/18/99

8.6.5 Examples

Activating a payment:

<TRNUID>12345

<BANKID>1234567789

<ACCTID>12345

<ACCTTYPE>CHECKING

</BANKACCTTO>

</SVCADD>

<SVC>BPSVC

</ACCTRQ>

</ACCTTRNRQ>

A response:

<TRNUID>12345

<CODE>0

<SEVERITY>INFO

</STATUS>

<BANKID>1234567789

<ACCTID>12345

<ACCTTYPE>CHECKING

</BANKACCTTO>

</SVCADD>

<SVC>BPSVC

<SVCSTATUS>ACTIVE

</ACCTRS>

</ACCTTRNRS>

146 8.7 Name and Address Changes

8.7 Name and Address Changes

Users may request that an FI update the official name, address, phone, and e-mail information

using the <CHGUSERINFORQ>. All modified and unmodified elements are submitted in a

change user information request, <CHGUSERINFORQ>. The lack of inclusion of a field in a

change user request when that field was previously populated implies its deletion on the server.

The response reports all of the current values. An optional USERID has been added to message

set version 2 to facilitate the change of user info by proxy. An example of which would be a

customer service representative who might be asked by the end user to change their address. If

the USERID element is not present in CHGUSERINFO, then the USERID from the SONRQ is

assumed to be the identifier for the user in question. For security reasons, some of the fields in

the <ENROLLRQ> cannot be changed online, such as tax ID and userID.

The transaction tags are <CHGUSERINFOTRNRQ> and <CHGUSERINFOTRNRS>. These

messages are subject to synchronization, <CHGUSERINFOSYNCRQ>, and

<CHGUSERINFOSYNCRS>.

OFX 1.6 Specification 14710/18/99

8.7.1 Change User Information Request <CHGUSERINFORQ>

Tag Version Description

Change-user-information-request aggregate

V2 only User ID, A-32

First name of user, A-32

Middle name of user, A-32

Last name of user, A-32

<ADDR1>

Address line 1, A-32

<ADDR2>

Address line 2. Use of <ADDR2> requires the presence of

<ADDR1>, A-32

<ADDR3>

Address line 3. Use of <ADDR3> requires the presence of

<ADDR2>, A-32

<CITY>

City, A-32

<STATE>

State or province, A-5

Postal code, A-11

3-letter country code from ISO/DIS-3166, A-3

Daytime telephone number, A-32

Evening telephone number, A-32

<EMAIL>

Electronic e-mail address, A-80

</CHGUSERINFORQ>

148 8.7 Name and Address Changes

8.7.2 Change User Information Response <CHGUSERINFORS>

8.7.3 Status Codes

Tag Version Description

Change-user-information-request aggregate

V2 only User ID, A-32

First name of user, A-32

Middle name of user, A-32

Last name of user, A-32

<ADDR1>

Address line 1, A-32

<ADDR2>

Address line 2. Use of <ADDR2> requires the presence of

<ADDR1>, A-32

<ADDR3>

Address line 3. Use of <ADDR3> requires the presence of

<ADDR2>, A-32

<CITY>

City, A-32

<STATE>

State or province, A-5

Postal code, A-11

3=letter country code from ISO/DIS-3166, A-3

Daytime telephone number, A-32

Evening telephone number, A-32

<EMAIL>

Electronic e-mail address, A-80

Date and time of update datetime

</CHGUSERINFORS>

Code Meaning

0 Success (INFO)

2000 General error (ERROR)

6502 Unable to process embedded transaction due to out-of-date

<TOKEN> (ERROR)

13503 Cannot change user information (ERROR)

15508 Transaction not authorized (ERROR)

OFX 1.6 Specification 14910/18/99

8.7.4 Change User Information Synchronization

Change user information requests are subject to the standard data synchronization protocol. The

scope of these requests and the <TOKEN> is the user ID. The request and response tags are

<CHGUSERINFOSYNCRQ> and <CHGUSERINFOSYNCRS>.

8.7.4.1 Request <CHGUSERINFOSYNCRQ>

Tag Version Description

Activation synchronization request aggregate

Client synchronization option;

<TOKEN>, <TOKEN2>,

<TOKENONLY>, or

<TOKEN>

V1 only Previous value of <TOKEN> received for this type of

synchronization request from server; 0 for first-time

requests; token

V2 only Previous value of <TOKEN2> received for this type of

synchronization request from server; 0 for first-time

requests; token2

Request for just the current <TOKEN> without the

history, Boolean

Request for refresh of current state, Boolean

If Y, do not process requests if client <TOKEN> is out of

date, Boolean

Change user information request transactions (0 or more)

</CHGUSERINFOTRNRQ>

</CHGUSERINFOSYNCRQ>

150 8.7 Name and Address Changes

8.7.4.2 Response <CHGUSERINFOSYNCRS>

Tag Version Description

Payee-list-request aggregate

<TOKEN>

V1 only New synchronization token, token

V2 only New synchronization token, token2

Y if the token in the synchronization request is older

than the earliest entry in the server’s history table. In

this case, some responses have been lost.

N if the token in the synchronization request is newer

than or matches a token in the server’s history table.

Boolean

V2 only Optional error code (See section 6.4.4.), N-6.

Change user information response transactions (0 or

more)

</CHGUSERINFOSYNCRS>

OFX 1.6 Specification 15110/18/99

8.8 Signup Message Set Profile Information

A server must include the following aggregates as part of the profile <MSGSETLIST> response,

since every server must support at least the account information and service activation

messages. Servers indicate how enrollment should proceed: via the client, a given web page, or a

text message directing users to some other method (such as a phone call).

Tag Version Description

Signup-message-set-profile-information aggregate

Opening tag for V1 of the message set profile

information

Same as V2, other than <PREAUTH> element added

to V2

Common message set information, defined in

Chapter 7, "

FI Profile"

</MSGSETCORE>

Enrollment options. Choose one of

<CLIENTENROLL>,

<WEBENROLL>, or

<OTHERENROLL>.

Client-based enrollment supported

Y if account number is required as part of enrollment,

Boolean

</CLIENTENROLL>

-or-

Web-based enrollment supported

<URL>

URL to start enrollment process, URL

</WEBENROLL>

-or-

Some other enrollment process

Message to consumer about what to do next (for

example, a phone number), A-80

</OTHERENROLL>

Y if server supports client-based user information

changes, Boolean

Y if server can provide information on accounts with

SVCSTATUS available, N means client should expect

to ask user for specific account information, Boolean

152 8.8 Signup Message Set Profile Information

Y if server allows clients to make service activation

requests (<ACCTRQ>), N if server will only advise

clients via synchronization of service additions,

changes, or deletions. Boolean

</SIGNUPMSGSETV1>

Zero or more V2 message sets

Same as V1, other than <PREAUTH> element added

to V2

Common message set information, defined in

Chapter 7, "

FI Profile"

</MSGSETCORE>

Enrollment options. Choose one of

<CLIENTENROLL>,

<WEBENROLL>, or

<OTHERENROLL>.

Client-based enrollment supported

Y if account number is required as part of enrollment,

Boolean

</CLIENTENROLL>

-or-

Web-based enrollment supported

<URL2>

URL to start enrollment process, URL2

</WEBENROLL>

-or-

Some other enrollment process

Message to consumer about what to do next (for

example, a phone number), A-2000

</OTHERENROLL>

Y if server supports client-based user information

changes, Boolean

Y if server can provide information on accounts with

SVCSTATUS available, N means client should expect

to ask user for specific account information, Boolean

Y if server allows clients to make service activation

requests (<ACCTRQ>), N if server will only advise

clients via synchronization of service additions,

changes, or deletions. Boolean

Tag Version Description

OFX 1.6 Specification 15310/18/99

Y if server supports <PREAUTHTOKEN> for account

activation, Boolean.

1.6 add Y if server supports <USERID> field in the

<SIGNUPMSGSRQV2> wrapper. These OFX 1.6

additions must be explicitly supported by the server

before they are used by a client. The default for this

option is N. Boolean

</SIGNUPMSGSETV2>

</SIGNUPMSGSET>

Tag Version Description

154 8.8 Signup Message Set Profile Information

OFX 1.6 Specification 15510/18/99

CHAPTER 9 CUSTOMER TO FI COMMUNICATION

9.1 The E-Mail Message Set

The e-mail message set includes two messages: generic e-mail and generic MIME requests by

way of URLs. In OFX files, the message set names are EMAILMSGSV1 and EMAILMSGSV2.

9.2 E-Mail Messages

OFX allows consumers and FIs to exchange messages. The message body can be placed in HTML

so that FIs can provide some graphic structure to the message. Keep in mind that, as with regular

World Wide Web browsing, an OFX client might not support some or all of the HTML

formatting, so the text of the message must be clear on its own. Clients can request the server to

send graphics (the images referenced in an <IMG> tag) as part of the response file, or clients can

separately request those elements. If a server sends images, it should use the standard procedure

for incorporating external data as described in Chapter 2, "

Structure." Servers are not required to

support HTML or to send images, even if the client asks.

A user or an FI can originate a message. E-mail messages are subject to data synchronization so

that a server can send a response again if it is lost or if multiple clients use it.

Because e-mail messages cannot be replied to immediately, the response should just echo back

the original message (so that data synchronization will get this original e-mail message to other

clients). When the FI is ready to reply, it should generate an unsolicited response (<TRNUID>0)

and the client will pick this up during synchronization.

Client Sends Server Responds

Account information

From, To

Subject

Message

Account information

From, To

Subject

Message

Type

156 9.2 E-Mail Messages

9.2.1 Regular vs. Specialized E-Mail

Several services with OFX define e-mail requests and responses that contain additional

information specific to that service. To simplify implementation for OFX clients and servers, this

section defines a <MAIL> aggregate that OFX uses in all e-mail requests and responses. For

regular e-mail, the only additional information is an account-from aggregate and whether to

include images in the e-mail response or not.

When users want to send messages about service-specific problems, service-specific messages

are best. However, when service-specific mail transactions are not available, general mail is

acceptable.

9.2.2 Basic <MAIL> Aggregate

Tag Description

<MAIL>

Core e-mail aggregate

User ID such as SSN, A-32

When message was created, datetime

<FROM>

Who the message is from, A-32

<TO>

Who the message should be delivered to, A-32

Subject of message (plain text, not HTML), A-60

Body of message, HTML-encoded or plain text depending on <USEHTML>,

HTML-encoded text - A-10000

Plain text - A-2000

</MSGBODY>

End of message.

Note: Unlike most other elements in OFX, <MSGBODY> always requires an

end tag.

Include images in the message body. Boolean

Y for HTML-formatted text. N for plain text. See section 9.2.2.2 for more

information. Boolean

</MAIL>

OFX 1.6 Specification 15710/18/99

9.2.2.1 <INCIMAGES>

The meaning of the <INCIMAGES> element depends on whether the element appears in a

request or response.

When used in a request, <INCIMAGES> indicates whether the client accepts mail that includes

images in the message body.

When used in a response, <INCIMAGES> indicates whether the server included images in the

message body.

9.2.2.2 <USEHTML>

The meaning of the <USEHTML> element depends on whether the element appears in a request

or response.

When used in a request, <USEHTML> indicates whether the client sends and accepts HTML-

formatted text in the message body. If a server receives a <xxxMAILSYNCRQ> request with

<USEHTML>Y set, the server should process the request whether or not it supports HTML mail.

If a server does not support HTML mail, it should simply set the <USEHTML> flag to N in any

transactions which are returned in the sync response.

When used in a request... Description

<INCIMAGES>Y

The client accepts mail that includes images in the message body. In

this case, the server can choose whether to send images in the response.

<INCIMAGES>N

The client does not accept mail that includes images in the message

body. In this case, the server must not send images in the response.

When used in a response… Description

<INCIMAGES>Y

The server included images in the message body.

<INCIMAGES>N

The server did not include images in the message body.

When used in a request… Description

<USEHTML>Y

The client is including HTML-formatted text in the message body. In

addition, the client will accept mail responses that include HTML-

formatted text in the message body. In this case, a server can choose

whether to respond with HTML-formatted text or plain text.

<USEHTML>N

The client is not including HTML-formatted text in the message body.

In addition the client will not accept mail responses that include

HTML-formatted text in the message body.

158 9.2 E-Mail Messages

When used in a response, <USEHTML> indicates whether the message body includes HTML-

formatted text or plain text.

Note: When using HTML for the message body, clients and servers are REQUIRED to

enclose the HTML in an SGML-marked section to protect the HTML markup:

<![CDATA[ ... html ... ]]>. For an example, see section 9.2.5

9.2.3 E-Mail <MAILRQ> <MAILRS>

E-mail is subject to synchronization. The transaction aggregate is <MAILTRNRQ> /

<MAILTRNRS> and the synchronization aggregate is <MAILSYNCRQ> / <MAILSYNCRS>.

In a response, the <TRNUID> is zero if this is an unsolicited message. Otherwise, it should

contain the <TRNUID> of the user’s original message. It is RECOMMENDED that servers

include the <MESSAGE> of the user’s message as part of the reply <MESSAGE>. The

<MESSAGE> contents can include carriage returns to identify desired line breaks.

When used in a response… Description

<USEHTML>Y

The server is including HTML-formatted text in the message body.

<USEHTML>N

The server is including only plain text in the message body.

Tag Description

E-mail-message-request aggregate

<MAIL>

Core e-mail aggregate

</MAIL>

</MAILRQ>

Tag Description

E-mail-message-response aggregate

<MAIL>

Core e-mail aggregate

</MAIL>

</MAILRS>

OFX 1.6 Specification 15910/18/99

9.2.3.1 Status Codes

Code Meaning

0 Success (INFO)

2000 General error (ERROR)

6502 Unable to process embedded transaction

due to out-of-date <TOKEN> (ERROR)

15508 Transaction not authorized (ERROR)

16500 HTML not allowed (ERROR)

16501 Unknown mail To: (ERROR)

160 9.2 E-Mail Messages

9.2.4 E-Mail Synchronization <MAILSYNCRQ> <MAILSYNCRS>

E-mail presents a special case with regards to synchronization. Since FIs will not immediately

reply to a user’s e-mail, the response to the user’s e-mail only echoes the request and confirms

that the e-mail was successfully received. The client receives the real response to the e-mail

following a synchronization request.

Note that this synchronization action expects only the basic <MAILRS> responses. Specialized e-

mail is received by means of their own synchronization requests.

Tag Version Description

E-mail-synchronization-request aggregate

Client synchronization

option; <TOKEN>,

<TOKEN2>,

<TOKENONLY>, or

<TOKEN>

V1 only Previous value of <TOKEN> received for this type of

synchronization request from server; 0 for first-time requests;

token

V2 only Previous value of <TOKEN2> received for this type of

synchronization request from server; 0 for first-time requests;

token2

Request for just the current <TOKEN> without the history,

Boolean

Request for refresh of current state, Boolean

If Y, do not process requests if client <TOKEN> is out of date,

Boolean

Y if the client accepts mail with images in the message body, N

if the client does not accept mail with images in the message

body, Boolean

Y if client wants an HTML response, N if client wants plain text,

Boolean

Mail-transaction-request aggregate (0 or more)

</MAILTRNRQ>

</MAILSYNCRQ>

OFX 1.6 Specification 16110/18/99

9.2.5 E-Mail Example

In this example, a consumer requests information about the checking statement just

downloaded. Since the financial institution will not immediately answer the inquiry, the

immediate response only echoes the consumer’s request and confirms that the request was

successfully received.

The client receives the real response at a later time following a mail synchronization request. For

an example of the mail synchronization request and response, see section 9.2.5.1

Note: This example omits the <OFX> top level and the signon <SONRQ>. Since this

example uses HTML for the message body, it must protect the HTML content in an

SGML CDATA-marked section.

The request:

<TRNUID>54321

<MAIL>

<USERID>123456789

<FROM>James Hackleman

<TO>Noelani Federal Savings

<SUBJECT>What do I need to earn interest?

<DTCREATED>19960305

Tag Version Description

E-mail-synchronization-response. aggregate

<TOKEN>

V1 only Server history marker, token

V2 only Server history marker, token2

Y if the token in the synchronization request is older than the earliest

entry in the server’s history table. In this case, some responses have

been lost.

N if the token in the synchronization request is newer than or

matches a token in the server’s history table. Boolean

V2 only Optional error code (See section 6.4.4), N-6

Missing e-mail response transactions (0 or more)

</MAILTRNRS>

</MAILSYNCRS>

162 9.2 E-Mail Messages

<MSGBODY><![CDATA[<HTML><BODY>I didn’t earn any interest this

month. Can you please tell me what I need to do to earn interest on this

account?</BODY></HTML>

]]></MSGBODY>

<INCIMAGES>N

<USEHTML>Y

</MAIL>

</MAILRQ>

</MAILTRNRQ>

The response from the FI:

<TRNUID>54321

<CODE>0

<SEVERITY>INFO

</STATUS>

<MAIL>

<USERID>123456789

<FROM>James Hackleman

<TO>Noelani Federal Savings

<SUBJECT>What do I need to earn interest?

<DTCREATED>19960305

<MSGBODY><![CDATA[<HTML><BODY>I didn’t earn any interest this

month. Can you please tell me what I need to do to earn interest on this

account?</BODY></HTML>

]]></MSGBODY>

<INCIMAGES>N

<USEHTML>Y

</MAIL>

</MAILRS>

</MAILTRNRS>

9.2.5.1 E-Mail Synchronization Example

In the following example, the client has not yet received the reply to the e-mail sent in the

previous example, so its <TOKEN> is one less than the server’s. The server replies by giving the

current <TOKEN> and the missed response.

<TOKEN>101

<REJECTIFMISSING>N

<INCIMAGES>N

OFX 1.6 Specification 16310/18/99

<USEHTML>Y

</MAILSYNCRQ>

<TOKEN>102

<CODE>0

<SEVERITY>INFO

</STATUS>

<MAIL>

<USERID>123456789

<DTCREATED>19960307

<FROM>Noelani Federal Savings

<TO>James Hackleman

<SUBJECT>Re: What do I need to earn interest?

<MSGBODY>><![CDATA[<HTML><BODY>You need to maintain $1000 in

this account to earn interest. Because your balance was only $750 this

month, no interest was earned. You could also switch to our new Checking

Extra plan that always pays interest. Call us or check our web page

http://www.fi.com/check-plans.html for more information.

Sincerely,

Customer Service Department

Original message:

I didn’t earn any interest this month. Can you please tell me what I

need to do to earn interest on this account?</BODY></HTML>

]]></MSGBODY>

<INCIMAGES>N

<USEHTML>Y

</MAIL>

</MAILRS>

</MAILTRNRS>

</MAILSYNCRS>

164 9.3 Get HTML Page

9.3 Get HTML Page

Some responses (<PROFRS> and <FINDBILLERRS> for example) contain values that are URLs

intended to be separately fetched by clients. Clients can use their own HTTP libraries to perform

this fetch outside of the OFX specification. However, to insulate clients against changes in

transport technology, and to allow for fetches that require the protection of an authenticated

signon by a specific user, OFX defines a transaction roughly equivalent to an HTTP Get. Any

MIME type can be retrieved, including images as well as HTML pages.

When a <GETMIMERQ> request appears in a request file and no error occurs in processing, the

server must return a response file containing multiple entities (defined in the MIME protocol to

include the MIME headers and content for one part of the transmission). Such a response file has

content type “multipart/x-mixed-replace”, as discussed in section 2.1

. One entity contains the

OFX response. Other entities contain the content of individual retrievals corresponding to each

<GETMIMERS> in the OFX entity.

When multiple <GETMIMERS> responses (corresponding to successful <GETMIMERQ>

requests) appear in an OFX response entity, the server must return individual entities in the same

order as the corresponding response aggregates. Since the OFX response itself should be the only

entity with content type “application/x-ofx” in the response file, the client may find the

retrieved information in predictable locations within the multipart response.

9.3.1 MIME Get Request and Response <GETMIMERQ>

The following table lists the components of a request:

Tag Version Description

Get-MIME-request aggregate

<URL>

V1 only URL, URL

<URL2>

V2 only URL, URL2

</GETMIMERQ>

OFX 1.6 Specification 16510/18/99

The response simply echoes the URL. The actual response, whether HTML, an image, or some

other type, is always sent as a separate part of the file using multipart MIME.

9.3.1.1 Status Codes

9.3.2 MIME Example

A request:

<TRNUID>54321

<URL>http://www.fi.com/apage.html

</GETMIMERQ>

</GETMIMETRNRQ>

A response – the full file is shown here to illustrate the use of multipart MIME:

HTTP 1.0 200 OK

Content-Type: multipart/x-mixed-replace; boundary =boundary =XYZZY24x7

--XYZZY24x7

Content-Type: application/x-ofx

Content-Length: 8732

OFXHEADER:100

DATA:OFXSGML

Tag Version Description

Get-MIME-response aggregate

<URL>

V1 only URL, URL

<URL2>

V2 only URL, URL2

</GETMIMERS>

Code Meaning

0 Success (INFO)

2000 General error (ERROR)

2019 Duplicate request (ERROR)

16502 Invalid URL (ERROR)

16503 Unable to get URL (ERROR)

166 9.3 Get HTML Page

VERSION:160

SECURITY:TYPE1

ENCODING:USASCII

CHARSET:NONE

COMPRESSION:NONE

NEWFILUID:NONE

OLDFILEUID:NONE

<OFX>

<!-- signon not shown

message set wrappers not shown -->

<TRNUID>54321

<CODE>0

<SEVERITY>INFO

</STATUS>

<URL>http://www.fi.com/apage.html

</GETMIMERS>

</GETMIMETRNRS>

</OFX>

--XYZZY24x7

Content-Type: text/html

<HTML>

</HTML>

--XYZZY24x7--

OFX 1.6 Specification 16710/18/99

9.4 E-Mail Message Set Profile Information

If either or both of the messages in the e-mail message set are supported, the following aggregate

must be included in the profile <MSGSETLIST> response. If <EMAILMSGSET> is supported by

the server, you must also support <MAILSYNCRQ>.

Tag Description

E-mail-message-set-profile-information aggregate

Opening tag for V1 of the message set profile information

Common message set information, defined in Chapter 7, "FI Profile"

</MSGSETCORE>

Y if server supports <MAILRQ> request. N if server supports only the

<MAILSYNCRQ> request. Boolean

Y if server supports get MIME message, Boolean

</EMAILMSGSETV1>

Zero or more V2 message sets

Common message set information, defined in Chapter 7, "FI Profile"

</MSGSETCORE>

Y if server supports the <MAILRQ> request. If N, the server supports

only the <MAILSYNCRQ> request. Boolean

Y if server supports get MIME message, Boolean

</EMAILMSGSETV2>

</EMAILMSGSET>

168 9.4 E-Mail Message Set Profile Information

OFX 1.6 Specification 16910/18/99

CHAPTER 10 RECURRING TRANSACTIONS

OFX enables users to automate transactions that occur on a regular basis. Recurring transactions

are useful when a customer has payments or transfers, for example, that repeat at regular

intervals. The customer can create a “model” at the server for automatic generation of these

instructions. The model in turn creates payments or transfers until it is canceled or expires. After

the user creates a recurring model at the server, the server can relieve the user from the burden of

creating these transactions; it generates the transactions on its own, based on the operating

parameters of the model.

10.1 Creating a Recurring Model

The client must provide the following information to create a model:

◆ Type of transaction generated by the model (payment or transfer)

◆ Frequency of recurring transaction

◆ Total number of recurring transactions to generate

◆ Service-specific information, such as transfer date, payment amount, payee address

The model creates each transaction some time before its due date, usually thirty days. This

allows the user to retrieve the transactions in advance of posting. This also gives the user the

opportunity to modify or cancel individual transactions without changing the recurring model

itself.

When a model is created, it can generate several transactions immediately. The model does not

automatically return responses for the newly created transactions. It returns a response only to

the request that was made to create the model. For this reason, clients should send a

synchronization request along with the request to create a model. This allows the server to return

the newly created transaction responses, as well as the response to the request to set up a new

model.

170 10.2 Recurring Instructions <RECURRINST>

10.2 Recurring Instructions <RECURRINST>

The Recurring Instructions aggregate is used to specify the schedule for a repeating instruction.

It is passed to the server when a recurring transfer or payment model is first created.

10.2.1 Values for <FREQ>

Rules for calculating recurring dates of WEEKLY, BIWEEKLY, and TWICEMONTHLY are as

follows:

◆ WEEKLY = starting date for first transaction, starting date + 7 days for the second

◆ TWICEMONTHLY = starting date for first, starting date + 15 days for the second

◆ BIWEEKLY = starting date for first, starting date + 14 days for the second

Tag Description

Recurring-Instructions aggregate

Number of instructions

If this element is absent, the schedule is open-ended, N-3

<FREQ>

Frequency, see section 10.2.1

</RECURRINST>

Value Description

WEEKLY Weekly

BIWEEKLY Biweekly

TWICEMONTHLY Twice a month

MONTHLY Monthly

FOURWEEKS Every four weeks

BIMONTHLY Bimonthly

QUARTERLY Quarterly

SEMIANNUALLY Semiannually

ANNUALLY Annually

OFX 1.6 Specification 17110/18/99

Examples:

Start date of May 2: next transaction date for WEEKLY is May 9; TWICEMONTHLY is May 17; next

transfer date for BIWEEKLY is May 16.

Start date of May 20: next date for WEEKLY is May 27; TWICEMONTHLY is June 4; next date for

BIWEEKLY is June 3.

TWICEMONTHLY recurring transactions will occur each month on those days adjusting for weekends

and holidays. BIWEEKLY will occur every 14 days.

10.2.2 Examples

The following example illustrates the creation of a repeating payment. The payment repeats on a

monthly basis for 12 months. All payments are for $395.

The request:

<NINSTS>12

<FREQ>MONTHLY

</RECURRINST>

<BANKID>555432180

<ACCTID>763984

<ACCTTYPE>CHECKING

</BANKACCTFROM>

<TRNAMT>395.00

<PAYEEID>77810

<PAYACCT>444-78-97572

<DTDUE>19971115

<MEMO>Auto loan payment

</PMTINFO>

</RECPMTRQ>

172 10.2 Recurring Instructions <RECURRINST>

The response includes the <RECSRVRTID> that the client can

use to cancel or modify the model:

<RECSRVRTID>387687138

<NINSTS>12

<FREQ>MONTHLY

</RECURRINST>

<BANKID>555432180

<ACCTID>763984

<ACCTTYPE>CHECKING

</BANKACCTFROM>

<TRNAMT>395.00

<PAYEEID>77810

<PAYACCT>444-78-97572

<DTDUE>19971115

<MEMO>Auto loan payment

</PMTINFO>

</RECPMTRS>

OFX 1.6 Specification 17310/18/99

10.3 Retrieving Transactions Generated by a Recurring Model

Once created, a recurring model independently generates instructions. At the time the instance is

generated, its status is pending. At this point, the pending/spawned transaction is treated as a

single transaction, and the rules for what happens to this transaction are the same as if it had

been generated from an explicit request. Since the client has not directly generated these

transactions, the client has no record of their creation. To enable users to modify and/or cancel

these transactions, the client must use data synchronization in order to retrieve these

transactions. (Some message sets also support an inquiry request, which may be used once the

SRVRTID of the transaction is obtained via synchronization.)

The client has two purposes for synchronizing state with the server with respect to recurring

models:

◆ Retrieve any added, modified, or canceled recurring models

◆ Retrieve any added, modified, or canceled transactions generated by any models

The client must be able to synchronize with the state of any models at the server, as well as the

state of any transactions generated by the server.

10.4 Modifying and Canceling Individual Transactions

Once created and retrieved by the customer, recurring payments and transfers are almost

identical to customer-created payments or transfers. As with ordinary payments or transfers,

you can cancel or modify transactions individually. However, because servers generate these

transfers, they are different in the following respects:

◆ Recurring transactions must be retrieved as part of a synchronization request.

◆ Recurring transactions are related to a model. A server can modify or cancel transactions if

the model is modified or canceled.

10.5 Modifying and Canceling Recurring Models

A recurring model can be modified or canceled. When a model is modified, all transactions that

it generates in the future will change as well. The client can indicate whether transactions that

have been generated, but have not been sent, should be modified as well. The actual elements

within a transaction that can be modified differ by service. See the recurring sections within

Chapter 11, "

Banking," and Chapter 12, "Payments," for details. When a model is cancelled, the

server cancels any transactions that it has not yet sent.

If a client indicates that the modification or cancellation of a model should also affect its pending

transactions, those individual modifications/cancellations must appear in the appropriate

synchronization response the next time a synchronization request is made. For example, a

recurring payment cancellation request that affects pending payments should cause payment

174 10.5 Modifying and Canceling Recurring Models

cancellation responses to show up in the payment synchronization response for all pending

payments belonging to the model.

10.5.1 Examples

Canceling a recurring payment model requires the client to pass the <RECSRVRTID> of the

model. The client requests that pending payments also be canceled. The server cancels the model

immediately and notifies the client that the model was canceled.

The request:

<RECSRVRTID>387687138

<CANPENDING>Y

</RECPMTCANCRQ>

The response:

<RECSRVRTID>387687138

<CANPENDING>Y

</RECPMTCANCRS>

The server also cancels any payments that have been generated but not executed. In the example

shown above, the client would not learn of this immediately. To receive notification that all

pending payments were canceled, the client would need to send a synchronization request in the

file. The following example illustrates this.

OFX 1.6 Specification 17510/18/99

The next request file contains a synchronization request:

<TOKEN>12345

<REJECTIFMISSING>N

<BANKID>123432123

<ACCTID>516273

<ACCTTYPE>CHECKING

</BANKACCTFROM>

</PMTSYNCRQ>

The response file contains one response (assuming one payment was pending).

<TOKEN>123456

<BANKID>123432123

<ACCTID>516273

<ACCTTYPE>CHECKING

</BANKACCTFROM>

<TRNUID>0

<CODE>0

<SEVERITY>INFO

</STATUS>

<SRVRTID>1030155

</PMTCANCRS>

</PMTTRNRS>

</PMTSYNCRS>

176 10.6 Expired Models

Note that because requests are not guaranteed to be executed in order, a PMTSYNCRQ in the

same file as the RECPMTCANCRQ would not guarantee that the cancelled payments would be

returned, since the PMYSYNCRQ might be executed first. This is the reason two OFX files are

required in the example above.

10.6 Expired Models

A model should (preferably) expire after the last pending transfer/payment has been executed

for that model, rather than when the last transfer/payment has been spawned. This enables the

user to change and/or cancel the model (possibly, with the <MODPENDING>Y or

<CANPENDING>Y flags) during this period.

Models should show up in synchronization responses even after they have expired (at least for a

time), since the RECSRVRTID will be in payment synchronization responses and a client needs

to find the corresponding model. Servers may safely remove this information shortly after the

final payment or transfer has posted to the source account.

OFX 1.6 Specification 17710/18/99

CHAPTER 11 BANKING

OFX enables financial institution (FI) customers to keep their finances up-to-date and to manage

their bank accounts conveniently in several ways. Customers can download transactions and

update account balances on a daily basis. They can retrieve a closing statement that contains the

same information that they are accustomed to seeing on a paper statement. They can transfer

funds between accounts at a financial institution, either immediately upon going online or on a

regular schedule. Customers can schedule transfers between accounts on a recurring basis and

can transfer funds between accounts at different financial institutions. If necessary, customers

can request a wire funds transfer. OFX also enables requests to stop payment on pending checks.

Using customer notification, an FI can notify customers of important events regarding their

accounts, such as returned checks or deposits.

11.1 Consumer and Business Banking

OFX supports banking for both consumers and businesses. Some customers might use some

areas more heavily within OFX Banking (such as credit card download); other areas might be

more appropriate for businesses (such as wire transfers). Yet all of the functionality defined for

Banking is appropriate to some extent for both consumer and business applications.

11.2 Credit Card Data

Credit card data is available to OFX clients through the statement download facility. Statement

download provides a way to download credit card transaction data and balances on an as-

needed basis. Statement closing information can be made available to clients as well.

11.3 Common Banking Aggregates

This section describes several aggregates used throughout the Banking portion of OFX.

178 11.3 Common Banking Aggregates

11.3.1 Banking Account <BANKACCTFROM> and <BANKACCTTO>

OFX uses the Banking Account aggregates to identify an account at an FI. The aggregates contain

enough information to uniquely identify an account for the purposes of statement download, bill

payment, and funds transfer. <CCACCTFROM> identifies credit card accounts; see section

11.3.2

Tag Version Description

Bank-account-from aggregate

Bank identifier, A-9

Use of this field by country:

COUNTRY

BEL

CAN

CHE

DEU

ESP

FRA

GBR

ITA

NLD

USA

Interpretation

Bank code

Routing and transit number

Clearing number

Bankleitzahl

Entidad

Banque

Sort code

ABI

Not used (field contents ignored)

Routing and transit number

Branch identifier. May be required for some non-US banks, A-

Use of this field by country:

COUNTRY

BEL

CAN

CHE

DEU

ESP

FRA

GBR

ITA

NLD

USA

Interpretation

Not present

Oficina

Agence

Not present

CAB

Not present

Account number, A-22

OFX 1.6 Specification 17910/18/99

V1 only Type of account, see section 11.3.1.2

V2 only Type of account, see section 11.3.1.2

Checksum, A-22

Use of this field by country:

COUNTRY

BEL

CAN

CHE

DEU

ESP

FRA

GBR

ITA

NLD

USA

Interpretation

Check digits

Not present

D.C.

Clé

Not present

CIN

Not present

</BANKACCTFROM>

Tag Version Description

180 11.3 Common Banking Aggregates

Tag Version Description

Bank-account-to aggregate

Bank identifier, A-9

Use of this field by country:

COUNTRY

BEL

CAN

CHE

DEU

ESP

FRA

GBR

ITA

NLD

USA

Interpretation

Bank code

Routing and transit number

Clearing number

Bankleitzahl

Entidad

Banque

Sort code

ABI

Not used (field contents ignored)

Routing and transit number

Branch identifier. May be required for some banks, A-22

Use of this field by country:

COUNTRY

BEL

CAN

CHE

DEU

ESP

FRA

GBR

ITA

NLD

USA

Interpretation

Not present

Oficina

Agence

Not present

CAB

Not present

Account number, A-22

V1 only Type of account, see section 11.3.1.2

V2 only Type of account, see section 11.3.1.2

Checksum, A-22

Use of this field by country:

OFX 1.6 Specification 18110/18/99

COUNTRY

BEL

CAN

CHE

DEU

ESP

FRA

GBR

ITA

NLD

USA

Interpretation

Check digits

Not present

D.C.

Clé

Not present

CIN

Not present

V2 only Extended bank account-to information aggregate. This

aggregate is only present when <BANKACCTTO> appears

within the Bill Payment message set. See section 11.3.1.1

Presence of this field by country:

COUNTRY

BEL

CAN

CHE

DEU

ESP

FRA

GBR

ITA

NLD

USA

Interpretation

Not present

Required for payments and payees

Not present

Required for payments and payees

Not present

</EXTBANKACCTTO>

</BANKACCTTO>

Tag Version Description

182 11.3 Common Banking Aggregates

11.3.1.1 Extended Banking Account Information <EXTBANKACCTTO>

The <EXTBANKACCTTO> aggregate contains additional information used to identify an

account being used for a payment transfer and payee requests. It only appears within

<BANKACCTTO> aggregates that are used within the Bill Payment message set, and not inside

any version 1 message sets. The <EXTBANKACCTTO> aggregate is only used if COUNTRY is

CHE, DEU or ITA.

11.3.1.2 Account Types for <ACCTTYPE> and <ACCTTYPE2> Elements

Tag Version Description

V2 only Extended Bank-account-to aggregate

Bank name, A-32 (mandatory if COUNTRY is CHE, DEU or

ITA)

Bank branch name, A-32 (mandatory if COUNTRY is ITA)

Bank branch city, A-32 (mandatory if COUNTRY is CHE)

Bank branch postal code, A-11 (mandatory if COUNTRY is

CHE)

<CHE.PTTACCTID>

PTT account number for indirect payments, A-9 (optional if

COUNTRY is CHE)

</EXTBANKACCTTO>

Type Version Description

CHECKING Checking

SAVINGS Savings

MONEYMRKT Money Market

CREDITLINE Line of credit

CMA <ACCTTYPE2> only Cash Management Account

OFX 1.6 Specification 18310/18/99

11.3.2 Credit Card Account <CCACCTFROM> and <CCACCTTO>

OFX uses the Credit Card Account aggregate to identify a credit card account at an FI. The

aggregate contains enough information to uniquely identify an account for the purposes of

statement downloads and funds transfer. It is not necessary to support the Credit Card Message

Set in order to use the Credit card account aggregate.

The <CCACCTTO> aggregate contains the same elements.

Tag Description

Credit-card-account-from aggregate

Account number, A-22

Checksum for international banks, A-22

</CCACCTFROM>

184 11.3 Common Banking Aggregates

11.3.3 Bank Account Information <BANKACCTINFO>

OFX uses the bank account information aggregate to download account information from an FI.

It includes account number specification in <BANKACCTFROM> as well as the status of the

service.

Tag Version Description

Bank-account-information aggregate

Bank-account-from aggregate

</BANKACCTFROM>

Y if account supports transaction detail downloads, N if it is

balance-only, Boolean

Y if account is enabled as a source for an intrabank or

interbank transfer, Boolean

Y if account is enabled as a destination for an intrabank or

interbank transfer, Boolean

V1 only Status of the account

AVAIL = Available, but not yet requested

PEND = Requested, but not yet available

ACTIVE = In use

V2 only AVAIL = Available, but not yet requested

PEND = Requested, but not yet available

ACTIVE = In use

REJECTED = Rejected

V2 only This element is only relevant if <SVCSTATUS2>REJECTED

is specified, A-255

</BANKACCTINFO>

OFX 1.6 Specification 18510/18/99

11.3.4 Credit Card Account Information <CCACCTINFO>

OFX uses the credit card account information aggregate to download account information from

an FI. It includes credit card number specification in <CCACCTFROM> as well as the status of

the service.

Tag Version Description

Credit-card-account-information aggregate

Credit-card-account-from aggregate

</CCACCTFROM>

Y if account supports transaction detail downloads, N if it is

balance-only, Boolean

Y if account is enabled as a source for an intrabank or

interbank transfer, Boolean

Y if account is enabled as a destination for an intrabank or

interbank transfer, Boolean

V1 only Status of the account

AVAIL = Available, but not yet requested

PEND = Requested, but not yet available

ACTIVE = In use

V2 only AVAIL = Available, but not yet requested

PEND = Requested, but not yet available

ACTIVE = In use

REJECTED = Rejected

V2 only This element is only relevant if <SVCSTATUS2>REJECTED

is specified, A-255

</CCACCTINFO>

186 11.3 Common Banking Aggregates

11.3.5 Transfer Information <XFERINFO>

Many of the transfer requests and responses use an <XFERINFO> aggregate. This aggregate

identifies accounts that are part of the transfer, amount of money to be transferred, and the date

of the transfer.

The <DTDUE> in a response may have been adjusted by a server. For example, the server may

adjust <DTDUE> to comply with non-processing days. If a client sends a request to make a

transfer on July 4 and July 4 happens to be a non-processing day, the <DTDUE> in the response

may be July 4 (because the server hasn’t adjusted it yet), July 5 (because this server rolls dates

forward), or some other date. For this reason, a client should pay attention to the <DTDUE> in

the response.

OFX 1.6 Specification 18710/18/99

Tag Version Description

Transfer-information aggregate

Account-from options.

Choose either

<BANKACCTFROM> or

<CCACCTFROM>.

Account-from aggregate, see section 11.3.1

</BANKACCTFROM>

or-

Credit-card-account-from aggregate, see section 11.3.2

</CCACCTFROM>

Account-to options. Choose

either <BANKACCTTO> or

<CCACCTTO>.

Account-to aggregate, see section 11.3.1

</BANKACCTTO>

-or-

Credit-card-account-to aggregate, see section 11.3.2

</CCACCTTO>

Amount of the transfer, amount

This amount should be specified as a positive number.

<DTDUE>

Date that the transfer is to be sent. If the client does not

specify <DTDUE>, the transfer occurs as soon as possible.

<DTDUE> is required for scheduled or repeating transfers,

datetime

V2 only The value date when the funds must be available in

BANKACCTTO. This can potentially be set independently

of DTDUE, datetime

Note that for some countries (notably Italy), DTAVAIL can

be a date in the past. This field is only supported by the

server if the SUPPORTDTAVAIL element of the Intrabank

transfer profile is true (see section 11.13.2.2

This element is not used in the US.

<MEMO2>

V2 only Associated text content for the transfer, memo2

</XFERINFO>

188 11.3 Common Banking Aggregates

11.3.6 Transfer Processing Status <XFERPRCSTS>

The Transfer Processing Status aggregate contains the current processing status for a transfer.

This aggregate is intended to describe status changes to the associated transfer after creation. The

interpretation of the date value depends on the value of <XFERPRCCODE>.

11.3.6.1 Transfer Processing Status Values <XFERPRCCODE>

Tag Description

Transfer processing status aggregate

See section 11.3.6.1

Transfer processing date; value depends on <XFERPRCCODE>

</XFERPRCSTS>

Value Description

WILLPROCESSON Will be processed on <DTXFERPRC>

POSTEDON Posted on <DTXFERPRC>

NOFUNDSON Funds not available to make transfer on <DTXFERPRC>

CANCELEDON User canceled payment on <DTXFERPRC>

FAILEDON Unable to make transfer for unspecified reasons on <DTXFERPRC>

OFX 1.6 Specification 18910/18/99

11.4 Downloading Transactions and Balances

Statement download allows a customer to receive transactions and balances that are typically

part of a regular paper statement. Clients can retrieve transactions and balances on a daily basis

if they wish. Coupled with the information returned by statement closing information request

(see section 11.5

), a client can construct an “electronic statement” that contains all of the

information that appears on a regular paper statement.

Clients typically allow customers to view these transactions and guide customers through a

process of updating their account registers based on the downloaded transactions. By using

transaction IDs supplied by financial institutions, OFX makes it possible for clients to ensure that

a server downloads each transaction only once. The request also contains starting and ending

dates to limit the amount of downloaded data. Clients can remember the last date they received

data and use it as the starting date in the next request.

The messages in this chapter are appropriate for checking, savings, money market, credit card,

and line of credit accounts. Investment statement download is a superset of bank statement

download. Chapter 13, "

Investments," describes the messages specific to investment statement

download.

Statement download requires the client to designate an account for the download, and to

indicate if the server should download transactions and/or balances. If the client wishes to

download transactions, it can specify a date range that the transactions fall within.

The server returns transactions that match the date range (if the client specifies one), and balance

information for the account.

Client Sends Server Responds

Account information

Include transactions?

Date range

Transactions

Cycle-ending information

190 11.4 Downloading Transactions and Balances

11.4.1 Bank Statement Download

A client can request a download of balances separately from transaction detail. The server

downloads transactions only if the <INCTRAN> aggregate is present and the <INCLUDE> flag

is set to Y. The current ledger balance (and balance date) are always downloaded.

If a statement download request does not contain <DTSTART> or <DTEND> elements but does

request transactions and no transactions are found on the server, the response may or may not

include a <BANKTRANLIST> without any <STMTTRN> aggregates. The server should leave

out the useless <BANKTRANLIST>.

You can use the <STMTRQ> … <STMTRS> request and response pair to download transactions

and balances for checking, savings, money market, and line of credit accounts. Section 11.4.2

describes download for credit card accounts.

Clients and servers should interpret <DTSTART> and <DTEND> as described in Chapter 3,

"Common Aggregates, Elements, and Data Types."

11.4.1.1 Request <STMTRQ>

The <STMTRQ> request must appear within a <STMTTRNRQ> transaction wrapper.

Tag Description

Statement-request aggregate

Bank-account-from aggregate, see section 11.3.1

</BANKACCTFROM>

Include-transactions aggregate

Start date of statement requested, datetime

<DTEND>

End date of statement requested, datetime

Include transactions flag, Boolean

</INCTRAN>

</STMTRQ>

OFX 1.6 Specification 19110/18/99

11.4.1.2 Response <STMTRS>

A statement response comprises elements supplying various balances, plus zero or more

<STMTTRN> aggregates, each describing one statement transaction.

The <STMTRS> response must appear within a <STMTTRNRS> transaction wrapper.

See Chapter 3, "

Common Aggregates, Elements, and Data Types," for size and type information

for common elements (such as currency values).

Tag Description

Statement-response aggregate

Default currency for the statement, currsymbol

Account-from aggregate, see section 11.3.1

</BANKACCTFROM>

Statement-transaction-data aggregate

Start date for transaction data, date

<DTEND>

Value that client should send in next <DTSTART> request to ensure that

it does not miss any transactions, date

Opening tag for each statement transaction (0 or more), see section 11.4.3

</STMTTRN>

End tag for each statement transaction

</BANKTRANLIST>

Ledger balance aggregate

Ledger balance amount, amount

Balance date, datetime

</LEDGERBAL>

Available balance aggregate

Available balance amount, amount

Balance date, datetime

</AVAILBAL>

Marketing information (at most 1), A-360

</STMTRS>

192 11.4 Downloading Transactions and Balances

11.4.1.3 Status Codes

11.4.2 Credit Card Statement Download

The credit card download request is semantically identical to the bank statement download

request. However, the <CCSTMTRQ> aggregate contains the credit card request, not the

<STMTRQ> aggregate.

If a statement download request does not contain <DTSTART> or <DTEND> elements but does

request transactions and no transactions are found on the server, the response may or may not

include a <BANKTRANLIST> without any <STMTTRN> aggregates. The server should leave

out the useless <BANKTRANLIST>.

Code Meaning

0 Success

2000 General error (ERROR)

2002 General account error (ERROR)

2003 Account not found (ERROR)

2004 Account closed (ERROR)

2005 Account not authorized (ERROR)

2019 Duplicate request (ERROR)

2020 Invalid date (ERROR)

2027 Invalid date range (ERROR)

OFX 1.6 Specification 19310/18/99

11.4.2.1 Request <CCSTMTRQ>

The <CCSTMTRQ> request must appear within a <CCSTMTTRNRQ> transaction wrapper.

Tag Description

Credit-card-download-request aggregate

Credit-card-account-from aggregate

Account number, A-22

Checksum for international banks, A-22

</CCACCTFROM>

Include transactions

Start date of statement requested, datetime

<DTEND>

Ending date of statement requested, datetime

Include transactions flag, Boolean

</INCTRAN>

</CCSTMTRQ>

194 11.4 Downloading Transactions and Balances

11.4.2.2 Response <CCSTMTRS>

The credit card download response is semantically identical to the bank statement download

response. However, the <CCSTMTRS> aggregate contains the credit card response, not the

<STMTRS> aggregate.

The <CCSTMTRS> response must appear within a <CCSTMTTRNRS> transaction wrapper.

Tag Description

Credit-card-download-response aggregate

Default currency for the statement, currsymbol

Account from aggregate, see section 11.3.2

</CCACCTFROM>

Opening tag for statement transaction data

Start date for transaction data, date

<DTEND>

Value client should send in next <DTSTART> request to ensure that it

does not miss any transactions, date

Opening tag for each statement transaction (0 or more), see section 11.4.3

</STMTTRN>

</BANKTRANLIST>

Ledger-balance aggregate

Ledger balance amount, amount

Balance date, datetime

</LEDGERBAL>

Available balance aggregate

Available balance amount, amount

Balance date, datetime

</AVAILBAL>

Marketing information (at most 1), A-360

</CCSTMTRS>

OFX 1.6 Specification 19510/18/99

11.4.2.3 Status Codes

11.4.3 Statement Transaction <STMTTRN>

A <STMTTRN> aggregate describes a single transaction. It identifies the type of the transaction

and the date it was posted. The aggregate can also provide additional information to help the

customer recognize the transaction: check number, payee name, and memo. The transaction can

have a Standard Industrial Code that a client can use to categorize the transaction.

Each <STMTTRN> contains an <FITID> that the client uses to detect whether the server has

previously downloaded the transaction.

Transaction amounts are signed from the perspective of the customer. For example, a credit card

payment is positive while a credit card purchase is negative.

Code Meaning

0 Success

2001 Invalid account (ERROR)

2002 General account error (ERROR)

2003 Account not found (ERROR)

2004 Account closed (ERROR)

2005 Account not authorized (ERROR)

2019 Duplicate request (ERROR)

2020 Invalid date (ERROR)

2027 Invalid date range (ERROR)

Tag Version Description

Statement-transaction aggregate

Transaction type, see section 11.4.3.1 for possible values. This

element does not change the effect of the transaction upon

the balance (increases and decreases are indicated by the sign

of the <TRNAMT>).

Date transaction was posted to account, datetime

Date user initiated transaction, if known, datetime

Date funds are available (value date), datetime

Amount of transaction, amount

196 11.4 Downloading Transactions and Balances

<FITID>

Transaction ID issued by financial institution.

Used to detect duplicate downloads, FITID

If present, the FITID of a previously sent transaction that is

corrected by this record. This transaction replaces or deletes

the transaction that it corrects, based on the value of

<CORRECTACTION> below, FITID

Actions can be REPLACE or DELETE. REPLACE replaces

the transaction referenced by CORRECTFITID; DELETE

deletes it.

1.6 add Service provider name. Used to limit the scope of

<SRVRTID> or <SRVRTID2> when matching transactions

with OFX requests. This value is normally obtained from

<MSGSETCORE> in the FI Profile for the relevant service

provider. If <SPNAME> is specified, <SRVRTID> or

<SRVRTID2> is required. A-32

Note: This optional element has no default. The server

should include <SPNAME> whenever a <SRVRTID> or

<SRVRTID2> is available in the download. The client cannot

assume that a <SRVRTID> or <SRVRTID2> provided

without <SPNAME> will match a single OFX request. The

user might need to be consulted when a <SRVRTID> or

<SRVRTID2> has multiple potential matches.

V1 only Server assigned transaction ID; used for transactions

initiated by client, such as payment or funds transfer.

SRVRTID

V2 only Server assigned transaction ID; used for transactions

initiated by client, such as payment or funds transfer.

SRVRTID2

Check (or other reference) number, A-12

Reference number that uniquely identifies the transaction.

Can be used in addition to or instead of a <CHECKNUM>,

A-32

<SIC>

Standard Industrial Code, N-6

V1 only Payee identifier if available, A-12

V2 only Payee identifier if available, SRVRTID2

Payee options. Choose either

<NAME> or <PAYEE>.

<NAME>

Name of payee or description of transaction, A-32

Note: Provide NAME or PAYEE, not both

Tag Version Description

OFX 1.6 Specification 19710/18/99

or-

<PAYEE>

V1 only Payee aggregate, see section 12.5.3.1

</PAYEE>

V2 only Payee aggregate, see section 12.5.3.1

</PAYEE2>

Account-to options. Choose

either <BANKACCTTO> or

<CCACCTTO>.

If this was a transfer to an account and the account

information is available, see section 11.3.1

</BANKACCTTO>

or-

</CCACCTTO>

<MEMO>

V1 only Extra information (not in <NAME>), MEMO

<MEMO2>

V2 only Extra information (not in <NAME>), MEMO2

Currency options. Choose

either <CURRENCY> or

<ORIGCURRENCY>.

Currency, if different from CURDEF

</CURRENCY>

-or-

</ORIGCURRENCY>

</STMTTRN>

Tag Version Description

198 11.4 Downloading Transactions and Balances

11.4.3.1 Transaction types used in <TRNTYPE>

Transfers generated from a model are treated identically to individually requested transfers by

OFX. Therefore, they should have the transaction types listed below once they are processed.

Transfers initiated out of band with respect to OFX should also be handled in this fashion when

they appear in a statement download.

Type Description

CREDIT Generic credit

DEBIT Generic debit

INT Interest earned or paid

Note: Depends on signage of amount

DIV Dividend

FEE FI fee

SRVCHG Service charge

DEP Deposit

ATM ATM debit or credit

Note: Depends on signage of amount

POS Point of sale debit or credit

Note: Depends on signage of amount

XFER Transfer

CHECK Check

PAYMENT Electronic payment

CASH Cash withdrawal

DIRECTDEP Direct deposit

DIRECTDEBIT Merchant initiated debit

REPEATPMT Repeating payment/standing order

OTHER Other

OFX 1.6 Specification 19910/18/99

11.5 Statement Closing Information

OFX provides a way for customers to receive closing statement information that typically

appears as part of a paper statement. This information includes opening and closing dates and

balances for a statement period, as well as a detailed breakdown of debits, credits, fees, and

interest that are usually part of a paper statement. In addition to this information, clients receive

a date range for transactions that correspond to the closing statement. Clients might wish to use

this date range to retrieve transactions through statement download in order to present the user

with an “electronic” statement.

To request statement information, the client is REQUIRED to designate an account for the

download. The client can also specify a date range to limit the number of closing information

aggregates that the server returns. If the client does not specify a date range, the server returns as

many closing information aggregates as it can.

11.5.1 Statement Closing Download

You can use the <STMTENDRQ> …<STMTENDRS> request and response pair to download

statement closing information for checking, savings, money market, and line of credit accounts.

Section 11.5.3

describes download for credit card accounts.

11.5.1.1 Request <STMTENDRQ>

The <STMTENDRQ> request must appear within a <STMTENDTRNRQ> transaction wrapper.

Client Sends Server Responds

Account Information

Date range

Cycle-ending information (0 or more)

Tag Description

Closing-statement-request aggregate

Bank-account-from aggregate

</BANKACCTFROM>

Start date for statement closing information, datetime

<DTEND>

End date of statement closing information, datetime

</STMTENDRQ>

200 11.5 Statement Closing Information

11.5.1.2 Response <STMTENDRS>

The <STMTENDRS> response must appear within a <STMTENDTRNRS> transaction wrapper.

11.5.1.3 Status Codes

11.5.2 Non-Credit Card Statement <CLOSING>

A checking, savings, or money market account uses the <CLOSING> aggregate to describe

statement closing information.

The <FITID> provides a way for the client to distinguish one closing statement from another.

Tag Description

Closing-statement-response aggregate

Default currency used for closing information, currsymbol

Account from aggregate, see section 11.3.1

</BANKACCTFROM>

Statement information (0 or more), see section 11.5.2

</CLOSING>

</STMTENDRS>

Code Meaning

0 Success

2000 General error (ERROR)

2002 General account error (ERROR)

2003 Account not found (ERROR)

2004 Account closed (ERROR)

2005 Account not authorized (ERROR)

2019 Duplicate request (ERROR)

2020 Invalid date (ERROR)

2027 Invalid date range (ERROR)

OFX 1.6 Specification 20110/18/99

For each <CLOSING> aggregate returned, clients can retrieve corresponding transactions by

using <DTPOSTSTART> and <DTPOSTEND> as <DTSTART> and <DTEND> in a <STMTRQ>

request.

Tag Description

Non-credit-card-account-types aggregate

<FITID>

Unique identifier for this statement, FITID

Opening statement date, date

Closing statement date, date

Closing date of next statement, date

Opening statement balance, amount

Closing statement balance, amount

Minimum balance in statement period, amount

Total of deposits and credits, including interest, amount

Total of checks and debits, including fees, amount

Total of all fees, amount

Total of all interest, amount

Start date of transaction data for this statement, date

A client should be able to use this date in a <STMTRQ> to request

transactions that match this statement.

End date of transaction data for this statement, date

A client should be able to use this date in a <STMTRQ> to request

transactions that match this statement.

Marketing information (at most 1), A-360

Currency options. Choose

either <CURRENCY> or

</CURRENCY>

-or-

Currency, if different from CURDEF

</ORIGCURRENCY>

</CLOSING>

202 11.5 Statement Closing Information

11.5.3 Credit Card Statement Closing Request <CCSTMTENDRQ>

The credit card statement closing request is semantically identical to the bank statement closing

request. However, the <CCSTMTENDRQ> aggregate contains the credit card request, not the

<STMTENDRQ> aggregate.

The <CCSTMTENDRQ> request must appear within a <CCSTMTENDTRNRQ> transaction

wrapper.

11.5.4 Credit Card Statement Closing Response <CCSTMTENDRS>

The credit card statement closing response is semantically identical to the bank statement closing

response. However, the <CCSTMTENDRS> aggregate contains the credit card response, not the

<STMTENDRS> aggregate.

The <CCSTMTENDRS> response must appear within a <CCSTMTENDTRNRS> transaction

wrapper.

Tag Description

Credit-card-closing-statement-request aggregate

Credit-card-account-from aggregate

</CCACCTFROM>

Start date for statement closing information, datetime

<DTEND>

End date of statement closing information, datetime

</CCSTMTENDRQ>

Tag Description

Credit-card-closing-statement-response aggregate

Default currency for closing information, currsymbol

Account from aggregate, see section 11.3.2

</CCACCTFROM>

Statement information (0 or more). See section 11.5.4.2

</CCCLOSING>

</CCSTMTENDRS>

OFX 1.6 Specification 20310/18/99

11.5.4.1 Status Codes

11.5.4.2 Credit Card Statement <CCCLOSING>

A credit card account uses the <CCCLOSING> aggregate to describe statement closing

information.

The <FITID> provides a way for the client to distinguish one closing statement from another.

Code Meaning

0 Success

2000 General error (ERROR)

2002 General account error (ERROR)

2003 Account not found (ERROR)

2004 Account closed (ERROR)

2005 Account not authorized (ERROR)

2019 Duplicate request (ERROR)

2020 Invalid date (ERROR)

2027 Invalid date range (ERROR)

204 11.5 Statement Closing Information

For each <CCCLOSING> returned, clients should be able to retrieve corresponding transactions

by using <DTPOSTSTART> and <DTPOSTEND> as <DTSTART> and <DTEND> in a

<CCSTMTRQ> request.

Tag Description

Credit-card-statement-information aggregate

<FITID>

Unique identifier for this statement, FITID

Opening statement date, date

Closing statement date, date

Closing date of next statement, date

Opening statement balance, amount

Closing statement balance, amount

Payment due date, date

Minimum amount due, amount

Finance charges, amount

Total of payments and credits, amount

Total of purchases and cash advances, amount

Debit adjustments, amount

Current credit limit, amount

Start date of transaction data for this statement, date

A client should be able to use this date in a <CCSTMTRQ> to request

transactions that match this statement.

End date of transaction data for this statement, date

A client should be able to use this date in a <CCSTMTRQ> to request

transactions that match this statement.

Marketing information (at most 1), A-360

Currency options. Choose

either <CURRENCY> or

<ORIGCURRENCY>.

</CURRENCY>

-or-

Currency, if different from CURDEF

</ORIGCURRENCY>

</CCCLOSING>

OFX 1.6 Specification 20510/18/99

11.6 Stop Check

OFX supports a request to issue a stop payment for one or more outstanding checks. The stop

request can be for a single check or for a range of checks. There must be one request for each

check or range of checks the user wants to stop.

When stopping a single check, the client can provide a payee name and optionally an amount

instead of a check number to describe the check to stop. Not all servers can support this behavior.

Examples:

Stop check 22 – one request

Stop check to “Acme Lighting” – one request

Stop checks 200-224 – one request

Stop checks 275-280, 283 – two requests (first stops 275-280, the next stops 283)

Client Sends Server Responds

Account information

Check number(s) to

stop

-or-

Check description

Status for each check

206 11.6 Stop Check

11.6.1 Stop Check Add

Stop Check Add is subject to synchronization.

11.6.1.1 Request <STPCHKRQ>

The <STPCHKRQ> request must appear within a <STPCHKTRNRQ> transaction wrapper.

11.6.1.1.1 Check Range <CHKRANGE>

Tag Description

Stop-check-request aggregate

Account-from aggregate, see section 11.3.1

</BANKACCTFROM>

Check options. Choose

either<CHKRANGE> or

<CHKDESC>.

Check range aggregate, see section 11.6.1.1.1

</CHKRANGE>

-or-

Check description aggregate, see section 11.6.1.1.2

</CHKDESC>

</STPCHKRQ>

Tag Description

Check-range aggregate

Start check number to cancel, A-12

Ending check number to cancel; omit if only one check is to be

stopped, A-12

</CHKRANGE>

OFX 1.6 Specification 20710/18/99

11.6.1.1.2 Check Description <CHKDESC>

A check description must include a payee name or description. It can also include a check

number, the date the user wrote the check, and a transaction amount.

11.6.1.2 Response <STPCHKRS>

Consistent with all responses, the stop check response contains a global status that describes

whether the response could be delivered. If the server provides a response, it returns a

<STPCHKNUM> aggregate for each check for which the client requested a stop payment. Status

code 10000 should be returned if the stop check request is in process; a subsequent

synchronization should obtain an updated response with a final status.

The <STPCHKRS> response must appear within a <STPCHKTRNRS> transaction wrapper.

Tag Description

Check description aggregate

<NAME>

Payee name or description, A-32

Check number, A-12

Date on check, datetime

Amount, amount

</CHKDESC>

Tag Description

Stop-check-response aggregate

Default currency for stop check response, currsymbol

Account-from aggregate, see section 11.3.1

</BANKACCTFROM>

Stopped check aggregate (1 or more), see section 11.6.1.2.1

</STPCHKNUM>

<FEE>

Fee for stop check, amount

Description of fee, A-80

</STPCHKRS>

208 11.6 Stop Check

11.6.1.2.1 Stopped Check <STPCHKNUM>

This aggregate contains a status code that indicates whether or not a specific check was canceled.

Tag Description

Stopped-check-item aggregate

Check number, A-12

<NAME>

Payee name or description, A-32

Date on check, datetime

Amount, amount

Status code for individual stop check request

0 = OK

1 = rejected

100 = check not found

101 = check already posted

Further textual explanation, A-255

Currency options. Choose

either <CURRENCY> or

<ORIGCURRENCY>.

</CURRENCY>

-or-

Currency, if different from CURDEF

</ORIGCURRENCY>

</STPCHKNUM>

OFX 1.6 Specification 20910/18/99

11.6.2 Status Codes

Code Meaning

0 Success

2000 General error (ERROR)

2002 General account error (ERROR)

2003 Account not found (ERROR)

2004 Account closed (ERROR)

2005 Account not authorized (ERROR)

2019 Duplicate request (ERROR)

6502 Unable to process embedded

transaction due to out-of-date

<TOKEN> (ERROR)

10000 Stop check in process (INFO)

10500 Too many checks to process (ERROR)

210 11.7 Intrabank Funds Transfer

11.7 Intrabank Funds Transfer

OFX supports transferring funds between two accounts at the same financial institution. Funds

transfers in OFX can be immediate or scheduled. Scheduled transfers can repeat at specified

intervals.

Financial institutions can choose to support:

◆ Immediate transfers

◆ Immediate and scheduled transfers

◆ Immediate, scheduled, and recurring transfers

Recurring transfers require support for scheduled transfers.

In general, an OFX server may not choose which transactions to support unless the profile can be

used to indicate to the client that a transaction is not supported. However, immediate intrabank

funds transfers usually cannot be modified or canceled, so a server that does not support

scheduled transfers may return an error code on any request for cancel or modify. A preferred

approach would be to return status code 2016, which means the transfer may not be modified or

canceled because it is already committed. (An immediate transfer may not actually commit until

the end of the business day. For more information, see the discussion on the support of

INTRASYNCRQ in section 11.12.2

After a transfer has executed, the server can either issue a transfer modification response in the

sync or it can do nothing. In the latter case, it would be up to the client to get status from a

statement download. If a transfer fails, it is recommended, but not required, that a transfer

modification response with the appropriate XFERPRCCODE be sent in the sync.

In general, all Intrabank Funds Transfer requests are subject to synchronization. The only

exception occurs when the request is for an immediate transfer and the server is able to

successfully perform the transfer in real time. In that case, the server may choose whether or not

the transfer affects the sync history. After receiving an immediate response indicating that a

transfer took place in real time, the client must not expect the relevant token to change or to

receive information about that transfer in a later sync response.

Note: Servers choosing to ignore real time immediate transfers in the sync history

force additional clients to wait until the transfer appears in a statement download for

information about the transfer.

OFX 1.6 Specification 21110/18/99

11.7.1 Intrabank Funds Transfer Addition

The Intrabank Funds Transfer Add request provides a way for a client to set up a single transfer.

The request designates source and destination accounts and the amount of the transfer. The

client must provide a date if it has scheduled the transfer. Immediate funds transfers cannot be

modified or canceled.

Intrabank Funds Transfer Add is subject to synchronization.

11.7.1.1 Request <INTRARQ>

The <INTRARQ> request must appear within an <INTRATRNRQ> transaction wrapper.

11.7.1.2 Response <INTRARS>

A server cannot, in all cases, provide complete confirmation for the transfer. The server can

confirm only that it received the transfer instruction; and possibly whether it validated the

accounts, amount, and date specified in the transfer. For any transfer where the client does not

know the status at the time of the response, a server should confirm that it accepted the

instruction and indicate the expected posting date of the transfer. A client can pick up the

Client Sends Server Responds

Source account

Destination account

Amount

Date of transfer

(optional)

Server ID for the transfer

Source account

Destination account

Amount

Expected/actual posting

date

Tag Description

Intrabank-transfer-request aggregate

Transfer information aggregate, see section 11.3.5

</XFERINFO>

</INTRARQ>

212 11.7 Intrabank Funds Transfer

confirmation at a later date through a synchronization request. Servers should inform clients of

any errors found while processing this transaction using the <STATUS> aggregate. A response

containing <STATUS><CODE>0 and <XFERPRCSTS><XFERPRCCODE>FAILEDON should be

avoided for problems such as an invalid account or amount.

If the request is for an immediate transfer and the server can perform the transfer in real time, the

server should indicate whether the transfer succeeded and should return the date of the transfer

in <DTPOSTED>. In this case, synchronization is not required.

The <INTRARS> response must appear within an <INTRATRNRS> transaction wrapper.

Note: The server can deliver this response to a client immediately after the request is

made (for an immediate or one-time scheduled transfer). The server should also

return this response for any transfers that were generated by a model.

Tag Version Description

Intrabank-transfer-response aggregate

Default currency for the intrabank transfer response,

currsymbol

V1 only Server ID for this transfer, SRVRTID

V2 only Server ID for this transfer, SRVRTID2

Transfer information aggregate, see section 11.3.5

</XFERINFO>

Transfer-date options.

Choose either

<DTXFERPRJ> or

Projected date of the transfer; response can contain either a

<DTXFERPRJ> or a <DTPOSTED> but not both; datetime

-or-

Actual date of the transfer, datetime

V1 only If the response is generated by a recurring transfer model, this

ID references it, see section 11.10

, SRVRTID

V2 only If the response is generated by a recurring transfer model, this

ID references it, see section 11.10

, SRVRTID2

Transfer-processing status, see section 11.3.6

</XFERPRCSTS>

</INTRARS>

OFX 1.6 Specification 21310/18/99

11.7.1.3 Status Codes

Code Meaning

0 Success (INFO)

2000 General error (ERROR)

2002 General account error (ERROR)

2006 Source account not found (ERROR)

2007 Source account closed (ERROR)

2008 Source account not authorized (ERROR)

2009 Destination account not found (ERROR)

2010 Destination account closed (ERROR)

2011 Destination account not authorized

(ERROR)

2012 Invalid amount (ERROR)

2014 Date too soon (ERROR)

2015 Date too far in future (ERROR)

2019 Duplicate request (ERROR)

6502 Unable to process embedded transaction

due to out-of-date <TOKEN> (ERROR)

10504 Insufficient funds (ERROR)

214 11.7 Intrabank Funds Transfer

11.7.2 Intrabank Funds Transfer Modification

The client sends a Transfer Modification request to modify a scheduled transfer. Immediate

transfers cannot be modified, so this request should only be used for scheduled transfers. Once

created and retrieved by the customer, spawned transfers are almost identical to customer-

created transfers. (The exception is when a spawned transfer is modified or cancelled due to a

recurring modification or cancellation request.) As with ordinary transfers, you can cancel or

modify transactions individually. When modifying a transfer, the client must specify all of the

elements and aggregates within the <XFERINFO> aggregate that were specified when the

transfer was created, not just the elements and aggregates that the client wants to modify.

<SRVRTID> specifies the transfer the user wants to modify. Some servers cannot support the

modification of certain values. Servers must indicate this by returning status code 10505 when

the client requests an unsupported modification. Clients must not change <BANKACCTFROM>

or <CCACCTFROM> in a funds transfer modification.

Intrabank Funds Transfer Modification is subject to synchronization.

11.7.2.1 Request <INTRAMODRQ>

The <INTRAMODRQ> request must appear within an <INTRATRNRQ> transaction wrapper.

Tag Version Description

Modification-request aggregate

V1 only ID assigned by the server to the transfer being modified,

SRVRTID

V2 only ID assigned by the server to the transfer being modified,

SRVRTID2

Transfer information aggregate, see section 11.3.5

</XFERINFO>

</INTRAMODRQ>

OFX 1.6 Specification 21510/18/99

11.7.2.2 Response <INTRAMODRS>

This response normally just echoes the values passed by the client. However, if the status of a

scheduled transfer changes in any way, clients should expect to receive modification responses

when they synchronize with the server. For example, when a server completes a transfer, the

status of the transfer goes from pending to posted. Clients should expect servers to notify them of

this status change.

The <INTRAMODRS> response must appear within an <INTRATRNRS> transaction wrapper.

Tag Version Description

Modification-response aggregate

V1 only ID assigned by the server to the transfer being modified,

SRVRTID

V2 only ID assigned by the server to the transfer being modified,

SRVRTID2

Transfer information aggregate, see section 11.3.5

</XFERINFO>

Transfer processing status, see section 11.3.6

</XFERPRCSTS>

</INTRAMODRS>

216 11.7 Intrabank Funds Transfer

11.7.2.3 Status Codes

Code Meaning

0 Success (INFO)

2000 General error (ERROR)

2002 General account error (ERROR)

2006 Source account not found (ERROR)

2007 Source account closed (ERROR)

2008 Source account not authorized (ERROR)

2009 Destination account not found (ERROR)

2010 Destination account closed (ERROR)

2011 Destination account not authorized

(ERROR)

2012 Invalid amount (ERROR)

2014 Date too soon (ERROR)

2015 Date too far in future (ERROR)

2016 Transaction already committed (ERROR)

2017 Already canceled (ERROR)

2018 Unknown server ID (ERROR)

2019 Duplicate request (ERROR)

6502 Unable to process embedded transaction

due to out-of-date <TOKEN> (ERROR)

10500 Too many checks to process (ERROR)

10505 Cannot modify element (ERROR)

10514 Transaction already processed (ERROR)

OFX 1.6 Specification 21710/18/99

11.7.3 Intrabank Funds Transfer Cancellation

The client sends a Transfer Cancellation request to cancel a scheduled transfer, where

<SRVRTID> identifies the transfer. Immediate transfers cannot be canceled, so this request

should be used only for scheduled transfers.

Intrabank Funds Transfer Cancellation is subject to synchronization.

11.7.3.1 Request <INTRACANRQ>

The <INTRACANRQ> request must appear within an <INTRATRNRQ> transaction wrapper.

11.7.3.2 Response <INTRACANRS>

The <INTRACANRS> response must appear within an <INTRATRNRS> transaction wrapper.

Tag Version Description

Transfer-cancellation-request aggregate

V1 only ID of the transfer the user wants to cancel. The server must

have previously assigned this ID to a transfer. SRVRTID

V2 only ID of the transfer the user wants to cancel. The server must

have previously assigned this ID to a transfer. SRVRTID2

</INTRACANRQ>

Tag Version Description

Transfer-cancellation-response aggregate

V1 only ID of the transfer the user wants to cancel. The server must

have previously assigned this ID to a transfer. SRVRTID

V2 only ID of the transfer the user wants to cancel. The server must

have previously assigned this ID to a transfer. SRVRTID2

</INTRACANRS>

218 11.7 Intrabank Funds Transfer

11.7.3.3 Status Codes

11.7.3.4 DTDUE, DTPOSTED, and DTXFERPRJ in Immediate Transfers

The following is a list of what might be returned in an immediate mode transfer response. The

interpretation of each response is provided. All responses referenced in this section are

immediate and describe success conditions. That is, we are not attempting to describe the

INTRARS aggregates that may be returned within a INTRASYNCRS response. Further,

successful INTRARS aggregates for immediate transfers are not expected to appear in lite

synchronization INTRASYNCRS responses.

◆ DTDUE and INTRARQ

DTDUE should not be present if the client is requesting an immediate mode transfer. If it is, then this is

a client error, and will be treated by the server as if the client were attempting to create a scheduled

transfer.

◆ DTDUE, DTPOSTED, and DTXFERPRJ NOT returned in INTRARS

The client should interpret this from the server as indicating that the immediate transfer request was

processed in real-time.

◆ DTDUE only returned

DTDUE should not be present in the response to a request for an immediate transfer. If it were present,

the XFERINFO aggregate would not match that found in the request.

◆ DTPOSTED only returned

If this is not equal to today’s date and an earlier time than “now”, then this is a server error. Otherwise,

the client should interpret this as confirmation from the server that the request was processed in real-

time.

◆ DTXFERPRJ only returned

The client should interpret this as indication that the transfer request will be completed by the specified

date. The client may receive an INTRAMODRS or INTRARS with updated information about this

transfer when it is actually processed. That future INTRARS or INTRAMODRS will contain the

DTPOSTED to reflect when the transfer occurred. This response is not required for successful transfers

processed at the originally specified projected date and time.

Code Meaning

0 Success (INFO)

2000 General error (ERROR)

2016 Transaction already committed (ERROR)

2017 Already canceled (ERROR)

2018 Unknown server ID (ERROR)

2019 Duplicate request (ERROR)

6502 Unable to process embedded transaction due

to out-of-date <TOKEN> (ERROR)

10514 Transaction already processed (ERROR)

OFX 1.6 Specification 21910/18/99

11.8 Interbank Funds Transfer

The Interbank Funds Transfer Add request provides a way for a client to set up a single transfer

between accounts at different financial institutions. Like intrabank funds transfers, the request

designates source and destination accounts and the amount of the transfer. Also, as in intrabank

funds transfers, the FI must be able to authenticate the source account. However, interbank

funds transfers differ from intrabank funds transfers in the following respects:

◆ The routing and transit number of the destination account differs from the source account.

◆ At the discretion of an FI, the destination account can be subject to pre-notification.

◆ Source and destination accounts must be enabled for the Automated Clearing House (ACH).

Use the ACH system to implement the Interbank Funds Transfer, which is subject to the rules

and regulations governing the ACH network.

In all other respects, interbank funds transfers function like intrabank funds transfers. The user

can schedule them for a future date or request an immediate transfer. The user can modify or

cancel scheduled transfers, but not immediate transfers. Scheduled transfers can recur at regular

intervals.

11.8.1 Interbank Funds Transfer – US

In the United States, interbank funds transfers usually use only the <XFERINFO> portion of the

request and response.

Interbank Funds Transfer Add is subject to synchronization.

Client Sends Server Responds

Source account

Destination account

Amount

Date of transfer

(optional)

Server ID for the transfer

Source account

Destination account

Amount

Expected/actual posting

date

220 11.8 Interbank Funds Transfer

11.8.2 Interbank Funds Transfer – International Usage

In countries where the funds transfer is the basis of the payments system, the OFX payments

messages allow specifying payees by destination account (see Chapter 12, "

Payments").

Interbank Funds Transfer Add is subject to synchronization.

11.8.2.1 Interbank Funds Transfer Request <INTERRQ>

The <INTERRQ> request must appear within an <INTERTRNRQ> transaction wrapper.

Tag Description

Interbank-transfer-request aggregate

Transfer information aggregate, see section 11.3.5

</XFERINFO>

</INTERRQ>

OFX 1.6 Specification 22110/18/99

11.8.2.2 Interbank Funds Transfer Response <INTERRS>

The server cannot provide complete confirmation for interbank transfer. It can confirm only that

the FI received the transfer instruction and possibly validated the source account, amount, and

date specified in the transfer. Since the client does not know the status of the transfer at the time

of the response, the server should confirm that it accepted the instruction and indicate the

expected posting date of the transfer. The client can pick up the confirmation at a later date

through a synchronization request. Servers should inform clients of any errors found while

processing this transaction using the <STATUS> aggregate. A response containing

<STATUS><CODE>0 and <XFERPRCSTS><XFERPRCCODE>FAILEDON should be avoided

for problems such as an invalid account or amount.

The <INTERRS> response must appear within an <INTERTRNRS> transaction wrapper.

Tag Version Description

Interbank-transfer-response aggregate

Currency used in transfer, currsymbol

V1 only Server ID for this transfer, SRVRTID

V2 only Server ID for this transfer, SRVRTID2

XFERINFO

Transfer information aggregate, see section 11.3.5

XFERINFO

Transfer-date options.

Choose either

<DTXFERPRJ> or

Projected date of the transfer; response can contain either a

<DTXFERPRJ> or a <DTPOSTED> but not both; datetime

-or-

Actual date of the transfer, datetime

Server can generate a reference or check for the transfer, A-32

V1 only If server generates the response by a recurring transfer model,

this ID references it. SRVRTID

V2 only If server generates the response by a recurring transfer model,

this ID references it. SRVRTID2

Transfer-processing status, see section 11.3.6

</XFERPRCSTS>

</INTERRS>

222 11.8 Interbank Funds Transfer

Note: A server can deliver this response to a client immediately after the client makes

the request (for an immediate or one-time scheduled transfer). In response to a

synchronization request by a client, the server should provide a second response

containing complete status regarding the transfer. It should also return any transfers

that it generates by a model.

11.8.2.3 Status Codes

Code Meaning

0 Success (INFO)

2000 General error (ERROR)

2002 General account error (ERROR)

2006 Source account not found (ERROR)

2007 Source account closed (ERROR)

2008 Source account not authorized (ERROR)

2009 Destination account not found (ERROR)

2010 Destination account closed (ERROR)

2011 Destination account not authorized

(ERROR)

2012 Invalid amount (ERROR)

2014 Date too soon (ERROR)

2015 Date too far in future (ERROR)

2019 Duplicate request (ERROR)

6502 Unable to process embedded transaction

due to out-of-date <TOKEN> (ERROR)

10504 Insufficient funds (ERROR)

OFX 1.6 Specification 22310/18/99

11.8.3 Interbank Funds Transfer Modification